UxPlay/README.html

<h1
id="uxplay-1.72-airplay-mirror-and-airplay-audio-server-for-linux-macos-and-unix-also-runs-on-windows.">UxPlay
1.72: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix
(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><p><strong>NEW on github</strong>: Support for <strong>service
discovery using a Bluetooth LE “beacon”</strong> (as an alternative to
Bonjour/Rendezvous DNS-SD service discovery). The user must set up a
Bluetooth LE “beacon”, (a USB 4.0 or later “dongle” can be used). See
instructions below. The beacon runs independently of UxPlay and
regularly broadcasts a Bluetooth LE (“Low Energy”) 44 byte packet
informing nearby iOS/macOS devices of the local IPv4 network address of
the UxPlay server, which they can use to contact it on TCP port 7000.
Instructions for manually setting up such a beacon in Linux are <a
href="#bluetooth-le-beacon-setup">given below</a>. <strong>It is hoped
that users will submit Pull Requests contributing scripts for automating
beacon setup on all platforms. (Python may be an appropriate language
choice)</strong></p></li>
<li><p><strong>NEW on github</strong>: (for Linux/*BSD Desktop
Environments using D-Bus). New option <code>-scrsv &lt;n&gt;</code>
provides screensaver inhibition (e.g., to prevent screensaver function
while watching mirrored videos without keyboard or mouse activity): n =
0 (off) n=1 (on during video activity) n=2 (always on while UxPlay is
running). Tested on Gnome/KDE/Cinnamon/Mate/Xfce 4: may need adjustment
for other Desktop Environments (please report). (watch output of
<code>dbus-monitor</code> to verify that inhibition is working).
<em>Might not work on Wayland</em>.</p></li>
<li><p><strong>NEW on github</strong>: option -ca (with no filename
given) will now render Apple Music cover art (in audio-only mode) inside
UxPlay. (-ca <code>&lt;filename&gt;</code> will continue to export cover
art for display by an external viewer).</p></li>
<li><p><strong>NEW in v1.72</strong>: Improved Support for (YouTube) HLS
(HTTP Live Streaming) video with the new “-hls” option (introduced in
1.71).* <strong>Only streaming from the YouTube iOS app (in "m3u8"
protocol) is currently supported</strong>: (streaming using the AirPlay
icon in a browser window is <strong>not</strong> yet supported).Click on
the airplay icon in the YouTube app to stream video. <strong>Please
report any issues with this new feature of UxPlay</strong>.</p>
<p><em>The default video player for HLS is GStreamer playbin v3: use
“-hls 2” to revert to playbin v2 if some videos fail to play</em>.</p>
<ul>
<li>user-requested features: added support for setting a password (as an
alternative to on-screen pin codes) to control client access (-pw
option, see “man pw” or this README for details); added support for
setting initial client audio-streaming volume (-vol option), and output
of audio-mode metadata to file (for display by some external process,
-md option).</li>
</ul>
<p><strong>ISSUES</strong> <strong><em>(Please help to solve if you have
expertise)</em></strong></p>
<ul>
<li>in HLS video streaming from the YouTube app (-hls option), rendered
using GStreamer’s media player “playbin3” (or playbin2, with option -hls
2), we don’t understand how to correctly deal with “interstitials” (= 15
sec commercials) when “skip” is pressed on the client. (HLS is handled
by handlers in lib/http_handlers.h). (Should response to HTTP requests
POST /action (playlistRemove) and POST /Stop be modified? <em>Wireshark
data from HLS on an AppleTV model 3 with UN-upgraded original OS
(unencrypted communications) could be useful!</em></li>
</ul></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>”; on OpenBSD with
“<code>doas pkg_add 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>
<li><p>If your distribution does not supply UxPlay, or you want the
latest version, it is very easy to build it yourself: see the very <a
href="#building-uxplay-from-source">detailed instructions for building
UxPlay from source</a>. later in this document.</p></li>
</ul>
<h2 id="after-installation">After installation:</h2>
<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. Use option “uxplay -ca” to display any “Cover Art” that
accompanies the audio.</p></li>
<li><p>If you are using UxPlay just to mirror the client’s screen
(without showing videos that need audio synchronized with video), it is
best to use the option “uxplay -vsync no”.</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; the
location can also be set with “uxplay -rc <em>location</em>”). 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>For Linux/*BSD systems using D-Bus, the option
<code>-scrsv 1</code> inhibits the screensaver while there is video
activity on UxPlay (<code>-scrsv 2</code> inhibits it whenever UxPlay is
running).</p></li>
<li><p>For Linux systems using systemd, there is a
<strong>systemd</strong> service file <strong>uxplay.service</strong>
found in the UxPlay top directory of the distribution, and also
installed in <code>&lt;DOCDIR&gt;/uxplay/systemd/</code> (where DOCDIR
is usually <code>/usr/local/share/doc</code>), that allows users to
start their own instance of UxPlay as a rootless daemon: it should
either be added to the directory /etc/systemd/user, or the user can just
create their own systemd directory <code>~/.config/systemd/user/</code>
and then copy uxplay.service into it. To save uxplay terminal output to
a file ~/uxplay.log, uncomment the StandardOutput entry in
uxplay.service. Then</p>
<p><code>systemctl --user [start/stop/enable/disable/status] uxplay</code></p>
<p>can be used to control the daemon. If it is enabled, the daemon will
start at the user’s first login and stop when they no longer have any
open sessions. See
https://www.baeldung.com/linux/systemd-create-user-services for more
about systemd user services. If more than one user might simultaneously
run uxplay this way, they should specify distinct -p and -m options
(ports and deviceID) in their startup files. <strong>Note: it is NOT
recommended to run UxPlay as a root service.</strong></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>
<li><p>If UxPlay is used in a public space, there are security options
for requiring an AppleTV-style one-time pin (displayed on the terminal)
to be entered, or a password, and for barring/permitting client access
by their device ID. See options -pin, -reg, -pw, -restrict, -allow,
-block.</p></li>
</ul>
<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).
There is now an alternative Service discovery method, using a Bluetooth
LE “beacon” See below for <a
href="#bluetooth-le-beacon-setup">instructions</a>.</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 &lt;name&gt;</code> is used, the
accompanying cover art is also output to a periodically-updated file
<code>&lt;name&gt;</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 &lt; 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="building-uxplay-from-source">Building UxPlay from source</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&gt;=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 &lt; 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>
<li><p><strong>OpenBSD:</strong> (doas pkg_add) libplist
gstreamer1-plugins-base. avahi-libs must also be installed to provide
the dns_sd library; (avahi-main must also be installed). 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-&lt;plugin&gt;</code>. Values of
<code>&lt;plugin&gt;</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>
<li><p><strong>OpenBSD:</strong> Install gstreamer1-libav,
gstreamer-plugins-* (* = core, bad, base, good).</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.</p>
<p>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>
<p>Note that there is now an alternative Service Discovery method using
a Bluetooth LE beacon. See the instructions on <a
href="#bluetooth-le-beacon-setup">Bluetooth beacon setup</a>.</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>
Password authentication (-pw <em>pwd</em>) is also offered as an
alternative solution to pin codes: users need to know the password
<em>pwd</em> and enter it on their iOS/macOS device to access UxPlay,
when prompted (if <em>pwd</em> is not set, a displayed random pin code
must be entered at <strong>each</strong> new connection.)</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 &lt;id&gt;</code>, <code>-block &lt;id&gt;</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>You can now display (inside UxPlay) the accompanying “Cover Art”
from sources like Apple Music in Audio-Only (ALAC) mode with the option
<code>uxplay -ca</code>. <em>The older method of exporting cover art to
an external viewer remains available: run
“<code>uxplay -ca &lt;name&gt; &amp;</code>” in the background, then run
a image viewer with an autoreload feature: an example is “feh”: run
“<code>feh -R 1 &lt;name&gt;</code>” in the foreground; terminate feh
and then Uxplay with “<code>ctrl-C fg ctrl-C</code>”</em>.</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 &lt;videosink&gt;</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 &lt;audiosink&gt;</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 &lt; 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 &lt;videosink&gt;]</code>. The choice
<code>&lt;videosink&gt;</code> = <code>glimagesink</code> is sometimes
useful. With the Wayland video compositor, use
<code>&lt;videosink&gt;</code> = <code>waylandsink</code>. With
framebuffer video, use <code>&lt;videosink&gt;</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] &gt; FILE &amp;</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 since
macOS 12 Monterey, but is restricted to recent hardware. As well as
running on latest macOS, UxPlay can run on older macOS systems that will
cannot 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 &gt;= 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>: MacPorts is
now providing recent GStreamer releases: install pkgconf (“sudo port
install pkgconf”), then “sudo port install gstreamer1
gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good
gstreamer1-gst-plugins-bad gstreamer1-gst-libav”. (The following may no
longer be relevant: <em>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 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 are glimagesink (default choice made by autovideosink) and
osxvideosink. The window title does not show the Airplay server name,
but the window can be shared on Zoom. Because of issues with
glimagesink, you may find osxvideosink works better. The only available
audiosink is osxaudiosink.</p></li>
<li><p>The option -nc is currently used by default on macOS, This is a
workaround for window-closing problems with GStreamer videosinks on
macOS. This option can be canceled with “-nc no”, if not
needed.</p></li>
<li><p>In the case of glimagesink, the resolution settings “-s wxh” may
not affect the (small) initial OpenGL mirror window size, but the window
can be expanded using the mouse or trackpad.</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” terminal from the MSYS2 tab in the Windows
Start menu, and update the new MSYS2 installation with “pacman
-Syu”.</p>
<ul>
<li>_NEW: MSYS2 now recommends using the newer UCRT64 terminal
environment (which uses the newer Microsoft UCRT “Universal C RunTime
Library”, included as part of the Windows OS since Windows 10) rather
than the MINGW64 terminal environment (which uses the older Microsoft
MSVCRT C library, which has “legacy” status, but is available on all
Windows systems). If you wish to use the legacy MSVCRT library, to
support older Windows versions, modify the instructions below as
follows:</li>
</ul>
<ol type="1">
<li>change the MSYS2 terminal type from UCRT64 to MINGW64; (2) modify
mingw-w64-ucrt-x86_64-* package names to mingw-w64-x86_64-*, (just omit
“-ucrt”);</li>
<li>replace <code>ucrt64</code> by <code>mingw64</code> in directory
names._</li>
</ol>
<p>Open a new MSYS2 UCRT64 terminal, and install the gcc compiler and
cmake:</p>
<p><code>pacman -S mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-gcc</code></p>
<p>We will simply build UxPlay from the command line in the MSYS2
environment (using “<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>
<pre><code>`pacman -S mingw-w64-ucrt-x86_64-libplist mingw-w64-ucrt-x86_64-gstreamer mingw-w64-ucrt-x86_64-gst-plugins-base`</code></pre>
<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, you
can install the uxplay.exe executable in
<code>C:/msys64/ucrt64/bin</code> (plus manpage and documentation in
<code>C:/msys64/ucrt64/share/...</code>) with</p>
<p><code>cmake --install . --prefix $HOME/../../ucrt64</code></p>
<p>You can later uninstall uxplay by returning to the build directory
and running</p>
<p><code>ninja uninstall</code></p>
<p>(This assumes that certain files in the build directory were not
deleted since building UxPlay).</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-ucrt-x86_64-gst-&lt;plugin&gt;</code>, where
the required ones have <code>&lt;plugin&gt;</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-&gt;Update and Security-&gt;Windows Security-&gt;Firewall &amp;
network protection -&gt; 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 UCRT64 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 &#39;wasapisink device=\&quot;&lt;guid&gt;\&quot;&#39; </code></pre>
<p>where <code>&lt;guid&gt;</code> specifies an available audio device
by its GUID, which can be found using
“<code>gst-device-monitor-1.0 Audio</code>”: <code>&lt;guid&gt;</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 &lt;videosink&gt;</code> option, some choices for
<code>&lt;videosink&gt;</code> are <code>d3d12videosink</code>,
<code>d3d11videosink</code>, <code>d3dvideosink</code>,
<code>glimagesink</code>, <code>gtksink</code>,
<code>autovideosink</code>. <em>There have been reports of segfaults of
the newer d3d12 videodecoder on certain older Nvidia cards when the
image resolution changes, e.g., when the iOS client is rotated between
portrait and landcape modes: this was a GStreamer issue that is
apparently now fixed (a workaround is to use d3d11).</em></p>
<ul>
<li>With Direct3D 11.0 or greater, various options can be set using
e.g. <code>-vs "d3d11videosink &lt;options&gt;"</code> (see the
gstreamer videosink documentation for these videosinks). For
convenience, if no <code>&lt;options&gt;</code> are set, the option to
toggle in and out of fullscreen mode with the Alt-Enter key combination
is added.</li>
</ul>
<p>The executable uxplay.exe can also be run without the MSYS2
environment, in the Windows Terminal, with
<code>C:\msys64\ucrt64\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>-rc <em>file</em></strong> can also be used to specify the
startup file location: this overrides <code>$UXPLAYRC</code>,
<code>~/.uxplayrc</code>, etc.</p>
<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
&gt; 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 [v]</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. Optional [v] (allowed values 2 or 3,
default: 3) allows selection of the version of GStreamer’s "playbin"
video player to use for playing HLS video. <em>(Playbin v3 is the
recommended player, but if some videos fail to play, you can try with
version 2.)</em></p>
<p><strong>-scrsv n</strong>. (since 1.73) (So far, only implemented on
Linux/*BSD systems using D-Bus). Inhibit the screensaver in the absence
of keyboard input (e.g., while watching video), using the
org.freedesktop.ScreenSaver D-Bus service: n = 0: (off) n= 1 (on during
video activity) n=2 (always on). <em>Note: to verify this feature is
working, you can use <code>dbus-monitor</code> to view events on the
D-Bus; depending on the Desktop Environment, commands like
<code>gnome-session-inhibit -l</code>,
<code>xfce4-screensaver-commannd -q</code>, etc., should list UxPlay
when it is inhibiting the screensaver.</em></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>-pw</strong> [<em>pwd</em>]. (since 1.72). As an alternative
to -pin, client access can be controlled with a password. If a password
<em>pwd</em> (of length at least six characters) is set when uxplay
starts (usually set in the startup file, where it is stored as
cleartext), all users must know this password to connect to UxPlay (the
client prompts for it). This method uses HTTP md5 Digest authentication,
which is now regarded as providing weak security, but it is only used to
validate the uxplay password, and no user credentials are exposed. After
a successful authentication, the client stores the password, and will
use it initially for future authentications without prompting, so long
as the UxPlay deviceID has not changed (this initial authentication will
fail if the UxPlay password has changed). If <em>pwd</em> is
<strong>not</strong> specified with the -pw option when UxPlay starts, a
new random 4-digit pin code is generated and displayed on the UxPlay
terminal for <strong>each</strong> new connection, and must be entered
on the client (there are three chances to enter it, before it is
changed). <em>Note: -pin and -pw are alternatives: if both are specified
at startup, the earlier of these two options is discarded.</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>-vol <em>v</em></strong> Sets initial audio-streaming volume
(on client): range is [0:1], with 0.0 = mute, 1.0 = full volume
(<em>v</em> is a decimal number).</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 currently only works
with X11, Wayland, VAAPI, kms 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 was no longer needed by GStreamer-1.20.4 and backports
from it, but appears to again be required in GStreamer-1.22 and
later.</p>
<p><strong>-srgb</strong> A workaround for a failure to display
full-range 8-bit color [0-255], and instead restrict to limited range
[16-235] “legal BT709” HDTV format. The workaround works on x86_64
desktop systems, but does not yet work on Raspberry Pi. The issue may be
fixed in a future GStreamer release: it only occurs in Linux and
*BSD.</p>
<p><strong>-srbg no</strong>. Disables the -srgb option, which is
enabled by default in Linux and *BSD, but may be useless on Raspberry
Pi, and may be unwanted, as it adds extra processing load.</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</strong> (without specifying a filename) now displays
“cover art” that accompanies Apple Music when played in “Audio-only”
(ALAC) mode.</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 &amp;</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>-md <em>filename</em></strong> Like the -ca option, but
exports audio metadata text (Artist, Title, Genre, etc.) to file for
possible display by a process that watches the file for changes.
Previous text is overwritten as new metadata is received, and the file
is deleted when uxplay terminates.</p>
<p><strong>-reset n</strong> sets a limit of <em>n</em> consecutive
failures of the client to send feedback requests (these “heartbeat
signals” are sent by the client once per second to ask for a response
showing that the server is still online). After <em>n</em> missing
signals, 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 15 seconds; the value <em>n</em> = 0 means “no limit”.</p>
<p><strong>-nofreeze</strong> closes the video window after a reset due
to client going offline (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 &lt; 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 &lt;deviceID&gt;</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>-ble <em>filename</em></strong>. Enable Bluetooth beacon
Service Discovery. The PID and process name of the UxPlay process is
recorded in <em>filename</em>, which must be the full path to a
writeable file. (This file is created when UxPlay starts and deleted
when it stops.) <strong>See below for beacon setup
instructions.</strong></p>
<p><strong>-d [n]</strong> Enable debug output; optional argument n=1
suppresses audio/video packet data in 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="bluetooth-le-beacon-setup">Bluetooth LE beacon setup</h1>
<p>When uxplay is started with the option
<code>uxplay -ble &lt;path-to-writeable-file&gt;</code>, it writes a 20
byte data file containing (4 bytes) the process ID (PID) as a uint32_t
32-bit unsigned integer, and (16 bytes) up to 15 bytes of the process
name (usually “uxplay”) as a null-terminated string, padded with zeroes
to fill 16 bytes. The file is deleted if UxPlay is terminated normally
(without a segfault), and could be used to determine if an instance of
uxplay is running. <strong>This file is provided for possible future use
in a script for controlling the beacon, and will not be used
here</strong>.</p>
<p>You may need to use a cheap USB Bluetooth dongle if your system does
not have Bluetooth 4.0 or later, or will not let you use it for LE (Low
Energy) transmissions.</p>
<p>These instructions are tested on Linux using the Bluez Bluetooth
stack. They use the <code>hcitool</code> and <code>hciconfig</code>
utilities which directly access the HCI stack, and need elevated
privileges (use <code>sudo</code>). These utilities have been declared
“deprecated” and “obsolete” by BlueZ developers: on Debian-based Linux
<code>sudo apt install bluez</code> still provides <code>hcitool</code>,
but on some other Linux distributions, it is split off from the main
BlueZ package into an “extra” package with a name like
“bluez-deprecated”. If we get the AirPlay beacon to work using the newer
<code>bluetoothctl</code> utility, these instructions will be
updated.</p>
<ul>
<li><p><strong>These manual instructions will hopefully be soon
superseded by e.g. python scripts that automate beacon control, probably
using D-Bus on Linux. Please submit any such scripts you get working for
possible packaging together with UxPlay</strong>. Note that the Apple
Service Discovery beacon is not a standard “<strong>ibeacon</strong>”,
and cannot be set up with unmodified “ibeacon”-specific
applications.</p></li>
<li><p>For testing Bluetooth beacon Service Discovery on Linux, you will
need to suppress the avahi-daemon which provides DNS-SD Service
Discovery on UxPlay’s Host system (replace <code>mask</code> and
<code>stop</code> below by <code>unmask</code> and <code>start</code> to
restore DNS-SD service).;</p></li>
</ul>
<pre><code>$ sudo systemctl mask avahi-daemon.socket
$ sudo systemctl stop avahi-daemon
</code></pre>
<p>Then verify that uxplay will not start without the
<code>-ble &lt;filename&gt;</code> option.</p>
<p>Before starting, check that you have a Bluetooth device with
“<code>hcitool dev</code>”</p>
<pre><code>$hcitool dev
Devices:
        hci1    E8:EA:6A:7C:3F:CC
        hci0    08:BE:AC:40:A9:DC</code></pre>
<p>This shows two devices with their MAC addresses. You can use
“<code>hciconfig -i</code>” to see which version of Bluetooth they
implement: we require Bluetooth v4.0 or later. Choose which to use (we
will use hci0), and reset it.</p>
<pre><code>$ sudo hciconfig hci0 reset
</code></pre>
<ul>
<li><strong>Step 1.</strong> First reconfigure the Bluetooth device
(hci0):</li>
</ul>
<p><code>hcitool</code> sends HCI commands as a sequence of 1-byte
hexadecimal octets. It echoes the length (here <code>plen</code> = 15
bytes) and content of the sequence it sends to the Bluetooth HCI stack,
and of the 4-byte “HCI Event” response it gets. Only the last byte of
the response is important: <code>00</code> means the command succeded
(other values are error codes).</p>
<pre><code>
$ sudo hcitool -i hci0 cmd 0x08 0x0006 0xa0 0x00 0xa0 0x00 0x03 0x01 0x00  0x00 0x00 0x00 0x00 0x00 0x00 0x07 0x00 

&lt; HCI Command: ogf 0x08, ocf 0x0006, plen 15
  A0 00 A0 00 03 01 00 00 00 00 00 00 00 07 00 
&gt; HCI Event: 0x0e plen 4
  02 06 20 00 
</code></pre>
<p>The above command configures the beacon:
“<code>cmd 0x08 0x006</code>” means HCI LE (ogf=0x08) command number 6
(ocf=0x0006) of the Blutooth LE stack.</p>
<p>The first two message bytes “<code>0xa0 0x00</code>” means a 2-byte
“unsigned short” value 0x00a0. (uint16_t integers such as 0xabcd are
represented as two bytes “<code>0xcd, 0xab</code>”). This is the minimum
interval AdvMin between beacon broadcasts, which are essentially
simultaneous on all three advertising channels. The next two entries
represent the maximum interval AdvMax, also set to 0x00a0, which means
100 msec (200 msec would be 2 * 0x00a0 = 0x0140 or
“<code>0x40 0x01</code>”). Setting AdvMin = AdvMax fixes the interval
between transmissions. If AdvMin &lt; AdvMax, the timing of each
broadcast event relative to the previous one can be chosen flexibly to
not overlap with any other task the bluetooth socket is carrying out.
The allowed range of these parameters is 0x00a0 = 100 msec &lt;= AdvMin
&lt;= AdvMax &lt;= 0x4000 = 10.24 sec.</p>
<p>An Apple TV (Gen 3) seems to use a fixed interval of 180 msec =
0x0120 (“<code>0x20 0x01</code>”).</p>
<p>The sixth byte TxAdd = “<code>0x01</code>” says that a random MAC
“advertisement address”” AdvAddr for the Bluetooth device will be sent
with the advertisement. If you wish to send the true hardware MAC
address of the Bluetooth device, replace this byte by
“<code>0x00</code>”.</p>
<p><strong>These are the only parameters you might want to
vary</strong>. The fifth byte 0x03 is the Advertising PDU type
“ADV_NONCONN_IND” (a beacon that transmits without accepting
connections) and the fourteenth byte 0x07 is a flag 0000 0111 that says
to use all three Bluetooth LE advertising channels.</p>
<ul>
<li><strong>Step 2.</strong> (<strong>Optional: skip this if you changed
byte 6 of the initial configuration message from</strong>
“<code>0x01</code>” <strong>to</strong> “<code>0x00</code>”.) Use HCI LE
command 5 (ocf=0x0005) to set private “advertising address” AdvAddr,
which substitutes for the public MAC address of the Bluetooth
device.</li>
</ul>
<p>This uses six random bytes r1,..,r6 and enters them as
<code>r1 , r2 , r3,  r4,  r5, r0 = (r6 | 0x03)</code>, where the 6th
byte has been masked with 0x03 = 00000011 so its last two bits are on,
and the value r0 is restricted to 64 values “<code>0xrs</code>” where
the second hexadecimal digit <code>s</code> is one of {3, 7, b, f},
which indicates a “static random” private address that is guaranteed to
not change between device reboots. Note that Apple TV’s use random
private addresses without applying a mask to r6 to distinguish between
different types.</p>
<pre><code>
$sudo hcitool -i hci0 cmd 0x08 0x0005 0x52 0xaa 0xaa 0x3a 0xb4 0x2f 
&lt; HCI Command: ogf 0x08, ocf 0x0005, plen 6
  52 AA AA 3A B4 2F 
&gt; HCI Event: 0x0e plen 4
  02 05 20 00 </code></pre>
<p>On a Bluetooth packet sniffer with wireshark, this address displays
as: <strong>Advertising Address: 2f:b4:3a:aa:aa:52</strong></p>
<ul>
<li><strong>Step 3.</strong> Now provide the advertising message, with
HCI LE command 8 (ocf=0x0008):</li>
</ul>
<p>This sends a 32 byte message to the HCI LE stack, where the first
byte is the length (here 0x0c = 12 bytes) of the significant part of the
following 31 bytes: 12 significant bytes, padded with 19 zeros to a
total message length of 32 bytes. (<code>hcitool</code> requires a
message padded to the full 32 bytes, but only sends the significant
bytes to the Bluetooth LE stack.)</p>
<pre><code>$ sudo hcitool -i hci0 cmd 0x08 0x0008 0x0c 0x0b 0xff 0x4c 0x00 0x09 0x06 0x03 0x30  0xc0 0xa8 0x01 0xfd  0x00 0x00 0x00 0x00  0x00 0x00 0x00 0x00  0x00 0x00 0x00 0x00  0x00 0x00 0x00 0x00  0x00 0x00 0x00
&lt; HCI Command: ogf 0x08, ocf 0x0008, plen 32
  0C 0B FF 4C 00 09 06 03 30 C0 A8 01 FD 00 00 00 00 00 00 00 
  00 00 00 00 00 00 00 00 00 00 00 00 
&gt; HCI Event: 0x0e plen 4
  01 08 20 00 </code></pre>
<p>The only parts of this message that you must change are the four
bytes 10,11,12,13, of the IPv4 address, here
“<code>0xc0 0xa8 0x01 0xfd</code>”, (decimal 192 168 1 253, an IPv4
address 192.168.1.253) which should be an IPv4 address at which the
UxPlay server can receive requests from iOS/macOS clients at TCP port
7000. You need to find what IPv4 address will work on the computer that
hosts UxPlay (use <code>ifconfig</code>), convert each of the four
numbers from decimal to hexadecimal, and replace bytes 13-16 of the
message by them.</p>
<ul>
<li><strong>Step 4.</strong> Start advertising by the beacon with
Bluetooth LE command 10 (ocf = 0x000a) and 1-byte message
“<code>0x01</code>” = “on”.</li>
</ul>
<pre><code>$ sudo hcitool -i hci0 cmd 0x08 0x000a 0x01
&lt; HCI Command: ogf 0x08, ocf 0x000a, plen 1
  01 
&gt; HCI Event: 0x0e plen 4
  02 0A 20 00 </code></pre>
<p>(To stop advertising, use this command to send the 1-byte message
“<code>0x00</code>” = “off”.)</p>
<p>For creating a higher-level script, it might be useful to know that
the length 0C = 12 bytes advertisement sent in step 3 has a single
“Advertising Protocol Data Unit” (PDU):</p>
<ul>
<li>0B FF 4C 00 09 06 03 30 C0 A8 01 FD: length 0B = 11 bytes,
consisting of: FF ( type = manufacturer-specific) 4C 00 (manufacturer
code = 0x004c, Apple ) manufacturer data 09 06 03 30 C0 A8 01 FD</li>
</ul>
<p>The manufacturer data defined by Apple consists of a single Apple
data unit: 09 (Apple type = AirPlay), 06 (Apple data length 6 bytes)
Apple data 03 30 XX XX XX XX, broken down into 03 (flags: 0000 0011) 30
(a seed) XX XX XX XX (IPv4 network address, written as four hexadecimal
octets in standard order). (Apple TV’s use a random private “AdvAddr”
address as described above, and periodically update it at about 20 min
intervals, each time increasing the seed by 1.)</p>
<p>Apple TV’s also insert a type-1 (“Flags”) 2-byte PDU
“<code>02 01 1A</code>” before the manufacturer-specific PDU, increasing
the significant length of the message to 0xf = 15 bytes. It turns out
that the “Flags” PDU is “optional” for advertisements like beacons that
do not allow client connections: in our tests on v4.0 and later dongles,
Service Discovery still worked fine after dropping the “Flags” PDU.</p>
<p>Both Linux and Windows have high-level interfaces that support users
sending Advertising PDU’s, but restricted to type 0xff
“manufacturer-specific-data” only, without any “Flags”. These should be
used for automating beacon setup, and are: (Linux) Bluez <a
href="https://github.com/bluez/bluez/blob/master/test/example-advertisement">LEAdvertisingManager1</a>
and (Windows 10/11) <a
href="https://learn.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.advertisement.bluetoothleadvertisementpublisher">BluetoothLEAdvertisementPublisherClass</a>
(with an <a
href="https://github.com/MicrosoftDocs/windows-dev-docs/blob/docs/uwp/devices-sensors/ble-beacon.md">example</a>).</p>
<p><strong>We don’t know if these instructions can be modified to
advertise IPv6 addresses: if you know of any verified support for
Bluetooth LE IPv6 Service Discovery in newer AppleTV models, please let
us know. Simply replacing the 4-byte IPv4 address with a 16-byte IPv6
address (and adjusting the lengths at bytes 1, 5 and 10) does not seem
to work, although perhaps we did not find the right value for byte 11
(“Apple Flags”). If Apple’s Bluetooth LE Service Discovery has IPv6
support, we need to examine the beacon advertisement packet for IPv6
addresses with a Bluetooth sniffer.</strong></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 &lt;cmd&gt; avahi-daemon</code> or
<code>sudo service avahi-daemon &lt;cmd&gt;</code>, with
<code>&lt;cmd&gt;</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 &lt; 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 &lt;audiosink&gt;</code>” or
“<code>-vs &lt;videosink&gt;</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>&lt;audiosink&gt;</code> or
<code>&lt;videosink&gt;</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>xxxx 2025-08-11 Render Audio cover-art inside UxPlay with -ca option
(no file specified). (D-Bus based) option -scrsv <n> to inhibit
screensaver while UxPlay is running (Linux/*BSD only). Add support for
Service Discovery using a Bluetooth LE beacon.</p>
<p>1.72.2 2025-07-07 Fix bug (typo) in DNS_SD advertisement introduced
with -pw option. Update llhttp to v 9.3.0</p>
<p>1.72.1 2025-06-06 minor update: fix regression in -reg option; add
option -rc <rcfile> to specify initialization file; add “-nc no” to
unset “-nc” option (for macOS users, where -nc is default); add
user-installable systemd script for running UxPlay as an
always-available “rootless daemon”</p>
<p>1.72 2025-05-07. Improved HLS Live Streaming (YouTube) support,
including “scrub”. Add requested options -md &lt;filename&gt; to output
audio metadata text to a file for possible display (complements -ca
option), and -vol <v> option to set initial audio-streaming volume. Add
support password user access control with HTTP digest Authentication
(-pw [pwd]). If no pwd is set, a random pin is displayed for entry at
each new connection.</p>
<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 &gt;= 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 &lt;
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 &gt;=
1.1.1 from source.</h3>
<p>If you need to do this, note that you may be able to use a newer
version (OpenSSL-3.0.1 is known to work). You will need the standard
development toolset (autoconf, automake, libtool). Download the source
code from <a href="https://www.openssl.org/source/"
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 &gt;=
2.0.0 from source.</h3>
<p><em>(Note: on Debian 9 “Stretch” or Ubuntu 16.04 LTS editions, you
can avoid this step by installing libplist-dev and libplist3 from Debian
10 or Ubuntu 18.04.)</em> As well as the usual build tools (autoconf,
automake, libtool), you may need to also install some libpython*-dev
package. Download the latest source 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>