AirPlay Unix mirroring server
NEW in v1.73, up to v1.73.6 (March 2026):
Some YouTube app HLS videos now offer alternative language tracks (generated by AI dubbing). Language choices will be made in order of
preferences set with option -lang (or by environment variable $LANGUAGE, which "-lang" overrides). Format is -lang fr:es:en, where French ("fr") is
the first choice, if available, then Spanish ("es"), etc. $LANGUAGE has the same format: -lang (by itself) suppresses playing of
dubbed audio if $LANGUAGE is set.
Support for recording Mirror-mode/Audio-mode (but not HLS) Audio and Video to mp4 file (new option -mp4 [fn]).
Support for service discovery using a Bluetooth LE "beacon" for both Linux/*BSD and Windows (as an alternative to Bonjour/Rendezvous DNS-SD
service discovery) was introduced in v1.73 and improved in 1.73.4 - 1.73.6. This can be used on networks that do not allow the user to run a DNS_SD service.**
The user must run a Bluetooth LE "beacon", (Bluetooth 4.0 or later is needed, a cheap USD "dongle" will do.). The
beacon is managed by a Python >= 3.6 script uxplay-beacon.py. Loadable Python modules provide appropriate Bluetooth LE support for Linux, Windows,
and FreeBSD; macOS is only supported by the BleuIO USB dongle which uniquely has its own Bluetooth LE stack based on a Renesas SoC, and is seen by the
host as a serial modem (this can be used on all the operating systems supported by Uxplay, including other BSD variants). The beacon runs independently
of UxPlay. While UxPlay is running, the beacon regularly broadcasts a Bluetooth LE ("Low Energy") 46 byte
legacy-type advertisement informing nearby iOS/macOS devices of
the local IPv4 network address of the UxPlay server, and which TCP port to contact UxPlay on. Instructions
are given below.
option -vrtp <rest-of-pipeline> bypasses rendering by UxPlay, and instead
transmits rtp packets of decrypted h264 or h265 video to
an external renderer (e.g. OBS Studio) at an address specified in rest-of-pipeline.
Similarly, -artp <rest-of-pipeline> forwards decoded audio as L16 RTP packets.
Both options can be used together to forward video and audio (as separate concurrent streams) to external
applications. See Usage for more details and sample Gstreamer receiver pipelines.
(for Linux/*BSD Desktop Environments using D-Bus). New option -scrsv <n> 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 dbus-monitor to verify that inhibition is working). Might not work on Wayland.
option -ca (with no filename given) will now render
Apple Music cover art (in audio-only mode) inside
UxPlay. (-ca <filename> will continue to export cover art for
display by an external viewer).
Improved Support for (YouTube) HLS (HTTP Live Streaming) video with the new "-hls" option (introduced in 1.71).* Only streaming from the YouTube iOS app (in "m3u8" protocol) is currently supported: (streaming using the AirPlay icon in a browser window is not yet supported).Click on the airplay icon in the YouTube app to stream video. Please report any issues with this new feature of UxPlay.
The default video player for HLS is GStreamer playbin v3: use "-hls 2" to revert to the older GStreamer player playbin v2 if some videos fail to play.
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).
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"; on OpenBSD with
"doas pkg_add 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.
If your distribution does not supply UxPlay, or you want the latest version, it is very easy to build it yourself: see the very detailed instructions for building UxPlay from source. later in this document.
(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 <n>{=html}" 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. Use option "uxplay -ca" to display any "Cover Art" that accompanies the audio.
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".
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; the location can also be set with "uxplay -rc location").
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).
For Linux/*BSD systems using D-Bus, the option -scrsv 1 inhibits the screensaver while
there is video activity on UxPlay (-scrsv 2 inhibits it whenever UxPlay is running).
For Linux systems using systemd, there is a systemd service file uxplay.service
found in the UxPlay top directory of the distribution, and also installed
in <DOCDIR>/uxplay/systemd/ (where DOCDIR is usually /usr/local/share/doc), 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 ~/.config/systemd/user/ 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
systemctl --user [start/stop/enable/disable/status] uxplay
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. Note: it is NOT recommended to run UxPlay as a root service.
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 patched 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.
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.
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 o
No open issues yet, or sync has not completed.