Note: AirPlay2 multi-room audio streaming is not supported: use shairport-sync for that.
.
Install uxplay on Debian-based Linux systems with "sudo apt install uxplay"; on FreeBSD
with "sudo pkg install uxplay". Also available on Arch-based systems through AUR. Since v. 1.66,
uxplay is now also packaged in RPM format by Fedora 38 ("sudo dnf install uxplay").
For other RPM-based distributions which have not yet packaged UxPlay, a RPM "specfile" uxplay.spec is now provided with recent releases (see their "Assets"), and can also be found in the UxPlay source top directory. See the section on using this specfile for building an installable RPM package.
After installation:
(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
Troubleshooting below for more details); also open three UDP and three TCP ports for
Uxplay, and use the "uxplay -p " option (see "man uxplay" or "uxplay -h").
Even if you install your distribution's pre-compiled uxplay binary package, you may need to read the instructions below for running UxPlay to see which of your distribution's GStreamer plugin packages you should also install.
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.
Add any UxPlay options you want to use as defaults to a startup file ~/.uxplayrc
(see "man uxplay" or "uxplay -h" for format and other possible locations). In particular, if your system uses PipeWire audio or
Wayland video systems, you may wish to add "as pipewiresink" or "vs waylandsink" as defaults to the file. (Output from terminal commands "ps waux | grep pulse" or "pactl info" will contain "pipewire" if your Linux/BSD system uses it).
On Raspberry Pi: If you use Ubuntu 22.10 or earlier, GStreamer must
be patched to use hardware video decoding by the Broadcom GPU
(also recommended but optional
for Raspberry Pi OS (Bullseye): use option "uxplay -bt709" if you do not use the patch).
To (easily) compile the latest UxPlay from source, see the section Getting UxPlay.
This project is a GPLv3 open source unix AirPlay2 Mirror server for Linux, macOS, and *BSD. It was initially developed by antimof using code from OpenMAX-based RPiPlay, which in turn derives from AirplayServer, shairplay, and playfair. (The antimof site is no longer involved in development, but periodically posts updates pulled from the new main UxPlay site).
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).
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.
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 here, here and here; see also pyatv 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.
The UxPlay server and its client must be on the same local area network, on which a Bonjour/Zeroconf mDNS/DNS-SD server 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 Avahi, through the avahi-daemon service, and is included in most Linux distributions (this service can also be provided by macOS, iOS or Windows servers).
Connections to the UxPlay server by
iOS/MacOS clients can be initiated both in AirPlay Mirror mode (which streams
lossily-compressed AAC audio while mirroring the client screen,
or in the alternative AirPlay Audio mode which streams
Apple Lossless (ALAC) audio without screen mirroring. In Audio mode,
metadata is displayed in the uxplay terminal;
if UxPlay option -ca <name> is used,
the accompanying cover art is also output
to a periodically-updated file <name>, and can be viewed with
a (reloading) graphics viewer of your choice.
Switching between Mirror and Audio modes during an active connection is
possible: in Mirror mode, stop mirroring (or close the mirror window) and start an Audio mode connection,
switch back by initiating a Mirror mode connection; cover-art display stops/restarts as you leave/re-enter Audio mode.
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), but both video and audio content from DRM-free apps like "YouTube app" will be streamed by UxPlay in Mirror mode.
As UxPlay does not currently support 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), 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 (there are plans to support HLS video in future releases of UxPlay)
UxPlay uses GStreamer "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.
VAAPI for Intel and AMD integrated graphics, NVIDIA with "Nouveau" open-source driver
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 here, but this requires VAAPI to be supplemented with firmware extracted from the proprietary NVIDIA drivers.
NVIDIA with proprietary drivers
The nvh264dec 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 libcuda.so is installed. For GStreamer-1.16.3
or earlier, the plugin is called nvdec, and
must be built by the user.
Video4Linux2 support for h264 hardware decoding on Raspberry Pi (Pi 4B and older)
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. (For GStreamer < 1.22, see the UxPlay Wiki).
(New): Support for h265 (HEVC) hardware decoding on Raspberry Pi (Pi 4 model B and Pi 5)
Support is present, but so far satisfactory results have not been obtained. Pi model 5 only provides hardware-accelerated (GPU) decoding for h265 video, but not H264, as its CPU is powerful enough for satisfactory software H264 decoding
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 prior to v. 3.0.0 (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.
Either download and unzip UxPlay-master.zip, or (if git is installed): "git clone https://github.com/FDH2/UxPlay". You can also download a recent or earlier version listed in Releases.
(Adapt these instructions for non-Debian-based Linuxes or *BSD; for macOS, see specific instruction below). See Troubleshooting below for help with any difficulties.
You need a C/C++ compiler (e.g. g++) with the standard development libraries
installed. Debian-based systems provide a package "build-essential" for use
in compiling software. You also need pkg-config: if it is not found
by "which pkg-config", install pkg-config or its work-alike replacement
pkgconf. Also make sure that cmake>=3.5 is installed:
"sudo apt install cmake" (add build-essential and pkg-config
(or pkgconf) to this if needed).
Make sure that your distribution provides OpenSSL 1.1.1 or later, and libplist 2.0 or later. (This means Debian 10 "Buster" 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).
If you have a non-standard OpenSSL
installation, you may need to set the environment variable OPENSSL_ROOT_DIR
(e.g. , "export OPENSSL_ROOT_DIR=/usr/local/lib64" if that is where it is installed).
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 e.g. "~/my_gstreamer/lib/gstreamer-1.0/", set this location
with "export GSTREAMER_ROOT_DIR=$HOME/my_gstreamer/lib").
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:
Note: By default UxPlay will be built with optimization for the
computer it is built on; when this is not the case, as when you are packaging
for a distribution, use the cmake option -DNO_MARCH_NATIVE=ON.
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 IF the X11 development libraries are installed and detected. Install these with
"sudo apt install libx11-dev". If GStreamer < 1.20 is detected, a fix needed by
screen-sharing apps (e.g., Zoom) will also be made.
-DNO_X11_DEPS=ON.sudo apt install libssl-dev libplist-dev".
(unless you need to build OpenSSL and libplist from source).sudo apt install libavahi-compat-libdnssd-devsudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev. (*Skip if you built Gstreamer from source)cmake . (For a cleaner build, which is useful if you modify the source, replace this
by "mkdir build; cd build; cmake ..": you can then delete the contents of the
build directory if needed, without affecting the source.) Also add any cmake "-D" options
here as needed (e.g, -DNO_X11_DEPS=ON or -DNO_MARCH_NATIVE=ON).makesudo make install (you can afterwards uninstall with sudo make uninstall
in the same directory in which this was run).This installs the executable file "uxplay" to /usr/local/bin, (and installs a manpage to
somewhere standard like /usr/local/share/man/man1 and README
files to somewhere like /usr/local/share/doc/uxplay). (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).
**For those with RPM-based distributions, a RPM spec file uxplay.spec is also available: see Building an installable rpm package.
Red Hat, or clones like CentOS (now continued as Rocky Linux or Alma Linux): (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) (some of these may be in the "CodeReady" add-on repository, called "PowerTools" by clones)
Mageia, PCLinuxOS, OpenMandriva: 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.
openSUSE: (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).
Arch Linux (Also available as a package in AUR): (sudo pacman -Syu) openssl libplist avahi gst-plugins-base.
FreeBSD: (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.
First-time RPM builders should first install the rpm-build and rpmdevtools packages,
then create the rpmbuild tree with "rpmdev-setuptree". Then download and
copy uxplay.spec into ~/rpmbuild/SPECS. In that directory, run "rpmdev-spectool -g -R uxplay.spec" to download the corresponding
source file uxplay-*.tar.gz into ~/rpmbuild/SOURCES ("rpmdev-spectool" may also be just called "spectool"); then
run "rpmbuild -ba uxplay.spec" (you will need to install
any required dependencies this reports). This should create the uxplay RPM package in a subdirectory of ~/rpmbuild/RPMS.
(uxplay.spec 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.)
Next install the GStreamer plugins that are needed with sudo apt install gstreamer1.0-<plugin>.
Values of <plugin> required are:
Debian-based distributions split some of the plugin packages into smaller pieces: some that may also be needed include "gl" 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), "gtk3" (which provides the "-vs gtksink" videosink), and "x" for X11 support, although these may already be installed; "vaapi" is needed for hardware-accelerated h264 video decoding by Intel or AMD graphics (but not for use with NVIDIA using proprietary drivers). If sound is not working, "alsa"", "pulseaudio", or "pipewire" plugins may need to be installed, depending on how your audio is set up.
In some cases, because of patent issues, the libav plugin feature avdec_aac needed for decoding AAC audio in mirror mode is not provided in the official distribution: get it from community repositories for those distributions.
Red Hat, or clones like CentOS (now continued as Rocky Linux or Alma Linux): Install gstreamer1-libav gstreamer1-plugins-bad-free (+ gstreamer1-vaapi for Intel/AMD graphics). In recent Fedora, gstreamer1-libav is renamed gstreamer1-plugin-libav. To get avdec_aac, install packages from rpmfusion.org: (get ffmpeg-libs from rpmfusion; on RHEL or clones, but not recent Fedora, also get gstreamer1-libav from there).
Mageia, PCLinuxOS, OpenMandriva: Install gstreamer1.0-libav gstreamer1.0-plugins-bad (+ gstreamer1.0-vaapi for Intel/AMD graphics). On Mageia, to get avdec_aac, install ffmpeg from the "tainted" repository, (which also provides a more complete gstreamer1.0-plugins-bad).
openSUSE: Install gstreamer-plugins-libav gstreamer-plugins-bad (+ gstreamer-plugins-vaapi for Intel/AMD graphics). To get avdec_aac, install libav* packages for openSUSE from Packman "Essentials"; recommendation: after adding the Packman repository, use the option in YaST Software management to switch all system packages for multimedia to Packman).
Arch Linux Install gst-plugins-good gst-plugins-bad gst-libav (+ gstreamer-vaapi for Intel/AMD graphics).
FreeBSD: Install gstreamer1-libav, gstreamer1-plugins, gstreamer1-plugins-* (* = core, good, bad, x, gtk, gl, vulkan, pulse, v4l2, ...), (+ gstreamer1-vaapi for Intel/AMD graphics).
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 $UXPLAYRC, (2) ~/.uxplayrc in the user's home
directory ("~"), (3) ~/.config/uxplayrc. The format is one option per line, omitting the initial "-" of
the command-line option. Lines in the configuration file beginning with "#" are treated as comments and ignored.
Run uxplay in a terminal window. On some systems, you can specify fullscreen mode with the -fs option, or
toggle into and out of fullscreen mode
with F11 or (held-down left Alt)+Enter keys. Use Ctrl-C (or close the window)
to terminate it when done. If the UxPlay server is not seen by the
iOS client's drop-down "Screen Mirroring" panel, check that your DNS-SD
server (usually avahi-daemon) is running: do this in a terminal window
with systemctl status avahi-daemon.
If this shows the avahi-daemon is not running, control it
with sudo systemctl [start,stop,enable,disable] avahi-daemon (on non-systemd systems, such as *BSD,
use sudo service avahi-daemon [status, start, stop, restart, ...]). 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: if a firewall is active, also open UDP port 5353 (for mDNS queries)
needed by Avahi. See Troubleshooting below for
help with this or other problems.
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 "-pin" and "-reg" in Usage for details, if you wish to use
it. 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.
By default, UxPlay is locked to
its current client until that client drops the connection; since UxPlay-1.58, the option -nohold 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 ( -restrict, -allow <id>, -block <id>) to control which clients are allowed to connect, using their
"deviceID" (which in Apple devices appears to be immutable).
In Mirror mode, GStreamer has a choice of two 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 "sync=false" method), with a GStreamer internal clock used to try to keep them synchronized. Starting with UxPlay-1.64, the other method (GStreamer's "sync=true" mode), which uses timestamps in the audio and video streams sent by the client, is the new default. 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.
The older method which does not drop late video frames
worked well on more powerful systems, and is still available with the UxPlay option "-vsync no"; 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.)
-async 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.AirPlay volume-control attenuates volume (gain) by up to -30dB: the decibel range -30:0 can be rescaled from Low:0, or Low:High, using the
option -db ("-db Low " or "-db Low:High "), Low must be negative. Rescaling is linear in decibels.
Note that GStreamer's audio format will "clip" any audio gain above +20db, so keep High below that level. The
option -taper provides a "tapered" AirPlay volume-control profile some users may prefer.
The -vsync and -async options
also allow an optional positive (or negative) audio-delay adjustment in milliseconds for fine-tuning : -vsync 20.5
delays audio relative to video by 0.0205 secs; a negative value advances it.)
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 -vsync.
Since UxPlay-1.54, you can display the accompanying "Cover Art" from sources like Apple Music in Audio-Only (ALAC) mode:
run "uxplay -ca <name> &" in the background, then run a image viewer with an autoreload feature: an example
is "feh": run "feh -R 1 <name>"
in the foreground; terminate feh and then Uxplay with "ctrl-C fg ctrl-C".
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 -vs <videosink>. Which videosinks are available depends on your operating system and
graphics hardware: use "gst-inspect-1.0 | grep sink | grep -e video -e Video -e image" to see what is available. Some possibilites on Linux/*BSD are:
glimagesink (OpenGL), waylandsink
xvimagesink, ximagesink (X11)
kmssink, fbdevsink (console graphics without X11)
vaapisink (for Intel/AMD hardware-accelerated graphics); for NVIDIA hardware graphics (with CUDA) use glimagesink combined
with "-vd nvh264dec" (or "nvh264sldec", a new variant which will become "nvh264dec" in GStreamer-1.24).
If the server is "headless" (no attached monitor, renders audio only) use -vs 0.
GStreamer also searches for the best "audiosink"; override its choice with -as <audiosink>. Choices on Linux include
pulsesink, alsasink, pipewiresink, oss4sink; see what is available with gst-inspect-1.0 | grep sink | grep -e audio -e Audio.
One common problem involves GStreamer
attempting to use incorrectly-configured or absent accelerated hardware h264
video decoding (e.g., VAAPI).
Try "uxplay -avdec" to force software video decoding; if this works you can
then try to fix accelerated hardware video decoding if you need it, or just uninstall the GStreamer vaapi plugin.
See Usage for more run-time options.
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). In this case you should explicitly use the "-vs kmssink" option, as without it, autovideosink does not find the correct videosink.
Raspberry Pi 5 does not provide hardware H264 decoding (and does not need it).
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 Raspberry Pi kernel tree; 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.
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.
On older distributions (GStreamer < 1.22), the v4l2 plugin needs a patch: see the UxPlay Wiki. 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.
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 these instructions before building UxPlay.
Raspberry Pi 3 Model B+ running a 32 bit OS can also access the GPU with the GStreamer OMX plugin
(use option "-vd omxh264dec"), but this is broken by Pi 4 Model B firmware. OMX support was removed from
Raspberry Pi OS (Bullseye), but is present in Buster.
H265 (4K) video is supported with hardware decoding by the Broadcom GPU on Raspberry Pi 5 models, as well as on Raspberry Pi 4 model B. While GStreamer seem to make use of this hardware decoding, satisfactory rendering speed of 4K video by UxPlay on these Raspberry Pi models has not yet been acheived. The option "-h265" is required for activating h265 support. A wired ethernet connection is preferred in this mode (and may be required by the client).
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).
The basic uxplay options for R Pi are uxplay [-vs <videosink>]. The
choice <videosink> = glimagesink is sometimes useful.
With the Wayland video compositor, use <videosink> = waylandsink.
With framebuffer video, use <videosink> = kmssink.
ssh user@remote_host
export DISPLAY=:0
nohup uxplay [options] > FILE &
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)
Note: A native AirPlay Server feature is included in macOS 12 Monterey, but is restricted to recent hardware. UxPlay can run on older macOS systems that will not be able to run Monterey, or can run Monterey but not AirPlay.
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).
It is also assumed that CMake >= 3.13 is installed:
this can be done with package managers MacPorts (sudo port install cmake),
Homebrew (brew install cmake), or by a download from
https://cmake.org/download/. Also install git if you will use it to fetch UxPlay.
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.
If you use Homebrew: brew install libplist openssl@3
if you use MacPorts: sudo port install libplist-devel openssl3
Otherwise, build libplist and openssl from source: see instructions near the end of this README; requires development tools (autoconf, automake, libtool, etc.) to be installed.
Next get the latest macOS release of GStreamer-1.0.
Using "Official" GStreamer (Recommended for both MacPorts and Homebrew users): install the GStreamer release for macOS from https://gstreamer.freedesktop.org/download/. (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 not install (or should uninstall) the GStreamer supplied by their package manager, if they use the "official" release.
Using Homebrew's GStreamer: 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 Homebrew gstreamer installation has recently been
reworked into a single "formula" named gstreamer, which now works without needing GST_PLUGIN_PATH to be
set in the enviroment. Homebrew installs gstreamer to (HOMEBREW)/lib/gstreamer-1.0 where (HOMEBREW)/* is
/opt/homebrew/* on Apple Silicon Macs, and /usr/local/* 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).
Using GStreamer installed from MacPorts: this is not recommended, as currently the MacPorts GStreamer is old (v1.16.2), unmaintained, and built to use X11:
(If you really wish to use the MacPorts GStreamer-1.16.2,
install pkgconf ("sudo port install pkgconf"), then
"sudo port install gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad gstreamer1-gst-libav".
For X11 support on macOS, compile UxPlay using a special cmake option -DUSE_X11=ON, and run
it from an XQuartz terminal with -vs ximagesink; older non-retina macs require a lower resolution
when using X11: uxplay -s 800x600.)
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).
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. Recommendation:
use the new UxPlay "no timestamp" option "-vsync no" (you can add a line "vsync no" in the uxplayrc configuration file).
On macOS with this installation of GStreamer, the only videosinks available seem to be glimagesink (default choice made by autovideosink) and osxvideosink. The window title does not show the Airplay server name, but the window is visible to screen-sharing apps (e.g., Zoom). The only available audiosink seems to be osxaudiosink.
The option -nc is always used, whether or not it is selected. This is a workaround for a problem with GStreamer videosinks on macOS: if the GStreamer pipeline is destroyed while the mirror window is still open, a segfault occurs.
In the case of glimagesink, the resolution settings "-s wxh" do not affect
the (small) initial OpenGL mirror window size, but the window can be expanded using the mouse or trackpad.
In contrast, a window created with "-vs osxvideosink" is initially big, but has the wrong aspect ratio (stretched image);
in this case the aspect ratio changes when the window width is changed by dragging its side;
the option -vs "osxvideosink force-aspect-ratio=true" can be used to make the window have the
correct aspect ratio when it first opens.
Download and install Bonjour SDK for Windows v3.0. You can download the SDK without any registration
at softpedia.com, or get it from the official Apple
site https://developer.apple.com/download (Apple makes
you register as a developer to access it from their site). This should install the Bonjour SDK as C:Program FilesBonjour SDK.
(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 https://www.msys2.org/. Accept the default installation location C:mysys64.
MSYS2 packages are installed with a variant of the "pacman" package manager used by Arch Linux. Open a "MSYS2 MINGW64" terminal from the MSYS2 tab in the Windows Start menu, and update the new MSYS2 installation with "pacman -Syu". Then install the MinGW-64 compiler and cmake
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc
The compiler with all required dependencies will be installed in the msys64 directory, with
default path C:/msys64/mingw64. Here we will simply build UxPlay from the command line
in the MSYS2 environment (this uses "ninja" in place of "make" for the build system).
Download the latest UxPlay from github (to use git, install it with pacman -S git,
then "git clone https://github.com/FDH2/UxPlay"), then install UxPlay dependencies (openssl is already
installed with MSYS2):
pacman -S mingw-w64-x86_64-libplist mingw-w64-x86_64-gstreamer mingw-w64-x86_64-gst-plugins-base
If you are trying a different Windows build system, MSVC versions of GStreamer for Windows are available from the official GStreamer site, but only the MinGW 64-bit build on MSYS2 has been tested.
cd to the UxPlay source directory, then "mkdir build" and "cd build". The build process assumes that
the Bonjour SDK is installed at C:Program FilesBonjour SDK. If it is somewhere else, set the enviroment
variable BONJOUR_SDK_HOME to point to its location. Then build UxPlay with
cmake ..
ninja
Assuming no error in either of these, you will have built the uxplay executable uxplay.exe in the
current ("build") directory. The "sudo make install" and "sudo make uninstall" features offered in the
other builds are not available on Windows; instead, the MSYS2 environment has
/mingw64/... available, and you can install the uxplay.exe executable
in C:/msys64/mingw64/bin (plus manpage and documentation in C:/msys64/mingw64/share/...) with
cmake --install . --prefix /mingw64
To be able to view the manpage, you need to install the manpage viewer with "pacman -S man".
To run uxplay.exe you need to install some gstreamer plugin packages
with pacman -S mingw-w64-x86_64-gst-<plugin>, where the required ones have <plugin> given by
Other possible MSYS2 gstreamer plugin packages you might use are listed in MSYS2 packages.
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 Windows Settings->Update and Security->Windows Security->Firewall & network protection -> allow an app through firewall. If your virus protection flags uxplay.exe as "suspicious" (but without a true malware signature) you may need to give it an exception.
Now test by running "uxplay" (in a MSYS2 terminal window). If you
need to specify the audiosink, there are two main choices on Windows: the older DirectSound
plugin "-as directsoundsink", and the more modern Windows Audio Session API (wasapi)
plugin "-as wasapisink", which supports additional options such as
uxplay -as 'wasapisink device="<guid>"'
where <guid> specifies an available audio device by its GUID, which can be found using
"gst-device-monitor-1.0 Audio": <guid> has a form
like {0.0.0.00000000}.{98e35b2b-8eba-412e-b840-fd2c2492cf44}. If "device" is not specified, the
default audio device is used.
If you wish to specify the videosink using the -vs <videosink> option, some choices for <videosink> are
d3d11videosink, d3dvideosink, glimagesink,
gtksink.
-vs "d3d11videosink fullscreen-toggle-mode=property fullscreen=true", or
get the ability to toggle into and out of fullscreen mode using the Alt-Enter key combination with
option -vs "d3d11videosink fullscreen-toggle-mode=alt-enter".
For convenience, these options will be added if just -vs d3d11videosink with or without the fullscreen
option "-fs" is used. (Windows users may wish to add "vs d3d11videosink" (no initial "-") to the
UxPlay startup options file; see "man uxplay" or "uxplay -h".)
The executable uxplay.exe can also be run without the MSYS2 environment, in
the Windows Terminal, with C:msys64mingw64binuxplay.
Options:
-" character) in the UxPlay startup file (either given by
environment variable $UXPLAYRC, or ~/.uxplayrc or ~/.config/uxplayrc); lines begining
with "#" are treated as comments, and ignored. Command line options supersede options in the startup file.-n server_name (Default: UxPlay); server_name@hostname will be the name that appears offering AirPlay services to your iPad, iPhone etc, where hostname is the name of the server running uxplay. This will also now be the name shown above the mirror display (X11) window.
-nh Do not append "@hostname" at the end of the AirPlay server name.
-h265 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 resolut "-s wxh" with h > 1080 is requested. The "-h265" option changes the default resolution ("-s" option) from 1920x1080 to 3840x2160, and leaves default maximum framerate ("-fps" option) at 30fps.
-pin [nnnn]: (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). (Add a line "pin" in the UxPlay startup file if you wish the UxPlay server to use the pin authentication protocol).
-reg [filename]: (since v1.68). If "-pin" is used, this option maintains a register of pin-authenticated "trusted clients" in $HOME/.uxplay.register (or optionally, in filename). 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). (Add a line "reg" in the startup file if you wish to use this feature.)
-vsync [x] (In Mirror mode:) this option (now the default) uses timestamps to synchronize audio with video on the server, with an optional audio delay in (decimal) milliseconds (x = "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.
-vsync no (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.
-async [x] (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 (x = "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. This might in principle be mitigated by using the -al 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.
-async no. 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
-async option set in a "uxplayrc" configuration file.
-db low[:high] Rescales the AirPlay volume-control attenuation (gain) from -30dB:0dB to low:0dB or low:high. The lower limit low must be negative (attenuation); the upper limit high can be either sign. (GStreamer restricts volume-augmentation by high 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".
-taper Provides a "tapered" Airplay volume-control profile (matching the one called "dasl-tapering" in shairport-sync): 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.)
-s wxh 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 height 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).
-s wxh@r 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.
-o 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: don't use this option unless there is some special reason to use it.
-fs uses fullscreen mode, but only works with X11, Wayland, VAAPI, and D3D11 (Windows).
-p 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].
If the -p option is not used, the ports are chosen dynamically (randomly), which will not work if a firewall is running.
-avdec 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.
-vp parser choses the GStreamer pipeline's h264 parser element, default is h264parse. Using quotes "..." allows options to be added.
-vd decoder 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.
-vc converter chooses the GStreamer pipeline's videoconverter element, instead of the default
value "videoconvert". When using Video4Linux2 hardware-decoding by a GPU,-vc v4l2convert will also use
the GPU for video conversion. Using quotes "..." allows some parameters to be included with the converter name.
-vs videosink 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, fullscreen mode is supported by the vaapisink plugin, and is
obtained using -vs "vaapisink fullscreen=true"; this also works with waylandsink.
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.
-vs 0 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.
-v4l2 Video settings for hardware h264 video decoding in the GPU by Video4Linux2. Equivalent to
-vd v4l2h264dec -vc v4l2convert.
-bt709 A workaround for the failure of the older Video4Linux2 plugin to recognize Apple's use of an uncommon (but permitted) "full-range color" variant of the bt709 color standard for digital TV. This is no longer needed by GStreamer-1.20.4 and backports from it.
-rpi Equivalent to "-v4l2 " (Not valid for Raspberry Pi model 5, and removed in UxPlay 1.67)
-rpigl Equivalent to "-rpi -vs glimagesink". (Removed since UxPlay 1.67)
-rpifb Equivalent to "-rpi -vs kmssink" (Removed since UxPlay 1.67)
-rpiwl Equivalent to "-rpi -vs waylandsink". (Removed since UxPlay 1.67)
-as audiosink 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. -as "alsasink device=..." 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.
-as 0 (or just -a) suppresses playing of streamed audio, but displays streamed video.
-al x specifies an audio latency x 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). (However, the client appears to ignore this reported latency, so this option seems non-functional.)
-ca filename provides a file (where filename can include a full path) used for output of "cover art"
(from Apple Music, etc.,) 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 (e.g. once per second.). To achieve this, run "uxplay -ca [path/to/]filename &" in the background,
then run the the image viewer in the foreground. Example, using feh as the viewer: run "feh -R 1 [path/to/]filename" (in
the same terminal window in which uxplay was put into the background). To quit, use ctrl-C fg ctrl-C to terminate
the image viewer, bring
