1957 lines
100 KiB
Plaintext
1957 lines
100 KiB
Plaintext
|
# UxPlay 1.71: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix (now also runs on Windows).
|
|||
|
|
|
|||
|
|
### **Now developed at the GitHub site <https://github.com/FDH2/UxPlay> (where ALL user issues should be posted, and latest versions can be found).**
|
|||
|
|
|
|||
|
|
- ***NEW in v1.71**: Support for (YouTube) HLS (HTTP Live Streaming)
|
|||
|
|
video with the new "-hls" option.* Click on the airplay icon in the
|
|||
|
|
YouTube app to stream video. (You may need to wait until
|
|||
|
|
advertisements have finished or been skipped before clicking the
|
|||
|
|
YouTube airplay icon.) **Please report any issues with this new
|
|||
|
|
feature of UxPlay**.
|
|||
|
|
|
|||
|
|
## Highlights:
|
|||
|
|
|
|||
|
|
- GPLv3, open source.
|
|||
|
|
- Originally supported only AirPlay Mirror protocol, now has added
|
|||
|
|
support for AirPlay Audio-only (Apple Lossless ALAC) streaming from
|
|||
|
|
current iOS/iPadOS clients. **Now with support for Airplay HLS
|
|||
|
|
video-streaming (currently only YouTube video).**
|
|||
|
|
- 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.
|
|||
|
|
- 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.
|
|||
|
|
- 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).
|
|||
|
|
- Support for server behind a firewall.
|
|||
|
|
- Raspberry Pi support **both with and without hardware video
|
|||
|
|
decoding** by the Broadcom GPU. *Tested on Raspberry Pi Zero 2 W, 3
|
|||
|
|
Model B+, 4 Model B, and 5.*
|
|||
|
|
- Support for running on Microsoft Windows (builds with the MinGW-64
|
|||
|
|
compiler in the unix-like MSYS2 environment).
|
|||
|
|
|
|||
|
|
Note: AirPlay2 multi-room audio streaming is not supported: use
|
|||
|
|
[shairport-sync](https://github.com/mikebrady/shairport-sync) for that.
|
|||
|
|
|
|||
|
|
## Packaging status (Linux and \*BSD distributions)
|
|||
|
|
|
|||
|
|
[](https://repology.org/project/uxplay/versions).
|
|||
|
|
|
|||
|
|
- 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](https://github.com/FDH2/UxPlay/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](#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](#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](#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: 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](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
To (easily) compile the latest UxPlay from source, see the section
|
|||
|
|
[Getting UxPlay](#getting-uxplay).
|
|||
|
|
|
|||
|
|
# Detailed description of UxPlay
|
|||
|
|
|
|||
|
|
This project is a GPLv3 open source unix AirPlay2 Mirror server for
|
|||
|
|
Linux, macOS, and \*BSD. It was initially developed by
|
|||
|
|
[antimof](http://github.com/antimof/Uxplay) using code from
|
|||
|
|
OpenMAX-based [RPiPlay](https://github.com/FD-/RPiPlay), which in turn
|
|||
|
|
derives from [AirplayServer](https://github.com/KqsMea8/AirplayServer),
|
|||
|
|
[shairplay](https://github.com/juhovh/shairplay), and
|
|||
|
|
[playfair](https://github.com/EstebanKubata/playfair). (The antimof site
|
|||
|
|
is no longer involved in development, but periodically posts updates
|
|||
|
|
pulled from the new main [UxPlay site](https://github.com/FDH2/UxPlay)).
|
|||
|
|
|
|||
|
|
UxPlay is tested on a number of systems, including (among others) Debian
|
|||
|
|
(10 "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](https://openairplay.github.io/airplay-spec/),
|
|||
|
|
[here](https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol)
|
|||
|
|
and [here](https://emanuelecozzi.net/docs/airplay2); see also
|
|||
|
|
[pyatv](https://pyatv.dev/documentation/protocols) 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](https://www.avahi.org), 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).**
|
|||
|
|
|
|||
|
|
- **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.**
|
|||
|
|
|
|||
|
|
### Possibility for using hardware-accelerated h264/h265 video-decoding, if available.
|
|||
|
|
|
|||
|
|
UxPlay uses [GStreamer](https://gstreamer.freedesktop.org) "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](https://nouveau.freedesktop.org/VideoAcceleration.html), 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](https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins).
|
|||
|
|
|
|||
|
|
- **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](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches))*.
|
|||
|
|
Pi model 5 has no support for hardware H264 decoding, as its CPU is
|
|||
|
|
powerful enough for satisfactory software H264 decoding
|
|||
|
|
|
|||
|
|
- **Support for h265 (HEVC) hardware decoding on Raspberry Pi (Pi 4
|
|||
|
|
model B and Pi 5)**
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
### Note to packagers:
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
# Getting UxPlay
|
|||
|
|
|
|||
|
|
Either download and unzip
|
|||
|
|
[UxPlay-master.zip](https://github.com/FDH2/UxPlay/archive/refs/heads/master.zip),
|
|||
|
|
or (if git is installed): "git clone https://github.com/FDH2/UxPlay".
|
|||
|
|
You can also download a recent or earlier version listed in
|
|||
|
|
[Releases](https://github.com/FDH2/UxPlay/releases).
|
|||
|
|
|
|||
|
|
- A recent UxPlay can also be found on the original [antimof
|
|||
|
|
site](https://github.com/antimof/UxPlay); that original project is
|
|||
|
|
inactive, but is usually kept current or almost-current with the
|
|||
|
|
[active UxPlay github site](https://github.com/FDH2/UxPlay) (thank
|
|||
|
|
you antimof!).
|
|||
|
|
|
|||
|
|
## Building UxPlay on Linux (or \*BSD):
|
|||
|
|
|
|||
|
|
### Debian-based systems:
|
|||
|
|
|
|||
|
|
(Adapt these instructions for non-Debian-based Linuxes or \*BSD; for
|
|||
|
|
macOS, see specific instruction below). See
|
|||
|
|
[Troubleshooting](#troubleshooting) below for help with any
|
|||
|
|
difficulties.
|
|||
|
|
|
|||
|
|
You need a C/C++ compiler (e.g. g++) with the standard development
|
|||
|
|
libraries installed. Debian-based systems provide a package
|
|||
|
|
"build-essential" for use in compiling software. You also need
|
|||
|
|
pkg-config: if it is not found by "`which pkg-config`", install
|
|||
|
|
pkg-config or its work-alike replacement pkgconf. Also make sure that
|
|||
|
|
cmake\>=3.10 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`").
|
|||
|
|
|
|||
|
|
- 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 [these
|
|||
|
|
instructions](https://github.com/FDH2/UxPlay/wiki/Building-latest-GStreamer-from-source-on-distributions-with-older-GStreamer-(e.g.-Raspberry-Pi-OS-).)
|
|||
|
|
. **Do this *before* building UxPlay**.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
- If X11 development libraries are present, but you wish to build
|
|||
|
|
UxPlay *without* any X11 dependence, use the cmake option
|
|||
|
|
`-DNO_X11_DEPS=ON`.
|
|||
|
|
|
|||
|
|
1. `sudo apt install libssl-dev libplist-dev`". (*unless you need to
|
|||
|
|
build OpenSSL and libplist from source*).
|
|||
|
|
2. `sudo apt install libavahi-compat-libdnssd-dev`
|
|||
|
|
3. `sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev`.
|
|||
|
|
(\**Skip if you built Gstreamer from source*)
|
|||
|
|
4. `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`).
|
|||
|
|
5. `make`
|
|||
|
|
6. `sudo 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).
|
|||
|
|
|
|||
|
|
### Building on non-Debian Linux and \*BSD
|
|||
|
|
|
|||
|
|
\*\*For those with RPM-based distributions, a RPM spec file uxplay.spec
|
|||
|
|
is also available: see [Building an installable rpm
|
|||
|
|
package](#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.
|
|||
|
|
|
|||
|
|
#### Building an installable RPM package
|
|||
|
|
|
|||
|
|
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.)
|
|||
|
|
|
|||
|
|
## Running UxPlay
|
|||
|
|
|
|||
|
|
### Installing plugins (Debian-based Linux distributions, including Ubuntu and Raspberry Pi OS) (*skip if you built a complete GStreamer from source*)
|
|||
|
|
|
|||
|
|
Next install the GStreamer plugins that are needed with
|
|||
|
|
`sudo apt install gstreamer1.0-<plugin>`. Values of `<plugin>` required
|
|||
|
|
are:
|
|||
|
|
|
|||
|
|
1. "**plugins-base**"
|
|||
|
|
2. "**libav**" (for sound),
|
|||
|
|
3. "**plugins-good**" (for v4l2 hardware h264 decoding)
|
|||
|
|
4. "**plugins-bad**" (for h264 decoding).
|
|||
|
|
|
|||
|
|
**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.
|
|||
|
|
|
|||
|
|
- Also install "**gstreamer1.0-tools**" to get the utility
|
|||
|
|
gst-inspect-1.0 for examining the GStreamer installation.
|
|||
|
|
|
|||
|
|
### Installing plugins (Non-Debian-based Linux or \*BSD) (*skip if you built a complete GStreamer from source*)
|
|||
|
|
|
|||
|
|
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](https://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](https://ftp.gwdg.de/pub/linux/misc/packman/suse/)
|
|||
|
|
"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).
|
|||
|
|
|
|||
|
|
### Starting and running UxPlay
|
|||
|
|
|
|||
|
|
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](#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](#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.)
|
|||
|
|
|
|||
|
|
- 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 `-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`.
|
|||
|
|
|
|||
|
|
Note that videosink options can set using quoted arguments to -vs:
|
|||
|
|
*e.g.*, `-vs "xvimagesink display=:0"`: 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 .
|
|||
|
|
|
|||
|
|
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](#usage) for more run-time options.
|
|||
|
|
|
|||
|
|
### **Special instructions for Raspberry Pi (tested on Raspberry Pi Zero 2 W, 3 Model B+, 4 Model B, and 5 only)**:
|
|||
|
|
|
|||
|
|
- 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](https://github.com/raspberrypi/linux); 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](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches).
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
- **It appears that when hardware h264 video decoding is used, the
|
|||
|
|
option -bt709 became needed again in GStreamer-1.22 and later.**
|
|||
|
|
|
|||
|
|
- 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](https://github.com/FDH2/UxPlay/wiki/Building-latest-GStreamer-from-source-on-distributions-with-older-GStreamer-(e.g.-Raspberry-Pi-OS-).)
|
|||
|
|
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 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).
|
|||
|
|
|
|||
|
|
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`.
|
|||
|
|
|
|||
|
|
- Tip: to start UxPlay on a remote host (such as a Raspberry Pi) using
|
|||
|
|
ssh:
|
|||
|
|
|
|||
|
|
```{=html}
|
|||
|
|
<!-- -->
|
|||
|
|
```
|
|||
|
|
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)
|
|||
|
|
|
|||
|
|
## Building UxPlay on macOS: **(Intel X86_64 and "Apple Silicon" M1/M2 Macs)**
|
|||
|
|
|
|||
|
|
*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](http://www.macports.org)
|
|||
|
|
(`sudo port install cmake`), [Homebrew](http://brew.sh)
|
|||
|
|
(`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.
|
|||
|
|
|
|||
|
|
- 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.)
|
|||
|
|
|
|||
|
|
**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](https://formulae.brew.sh/formula/gstreamer#default) 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_PREFIX/lib/gstreamer-1.0` where
|
|||
|
|
by default `HOMEBREW_PREFIX/*` 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).
|
|||
|
|
**New: the UxPlay build script will now also detect Homebrew
|
|||
|
|
installations in non-standard locations indicated by the environment
|
|||
|
|
variable `$HOMEBREW_PREFIX`.**
|
|||
|
|
|
|||
|
|
**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:
|
|||
|
|
|
|||
|
|
- Instead [build gstreamer
|
|||
|
|
yourself](https://github.com/FDH2/UxPlay/wiki/Building-GStreamer-from-Source-on-macOS-with-MacPorts)
|
|||
|
|
if you use MacPorts and do not want to use the "Official" Gstreamer
|
|||
|
|
binaries.
|
|||
|
|
|
|||
|
|
*(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.
|
|||
|
|
|
|||
|
|
## Building UxPlay on Microsoft Windows, using MSYS2 with the MinGW-64 compiler.
|
|||
|
|
|
|||
|
|
- tested on Windows 10 and 11, 64-bit.
|
|||
|
|
|
|||
|
|
1. Download and install **Bonjour SDK for Windows v3.0**. You can
|
|||
|
|
download the SDK without any registration at
|
|||
|
|
[softpedia.com](https://www.softpedia.com/get/Programming/SDK-DDK/Bonjour-SDK.shtml),
|
|||
|
|
or get it from the official Apple site
|
|||
|
|
[https://developer.apple.com/download](https://developer.apple.com/download/all/?q=Bonjour%20SDK%20for%20Windows)
|
|||
|
|
(Apple makes you register as a developer to access it from their
|
|||
|
|
site). This should install the Bonjour SDK as
|
|||
|
|
`C:\Program Files\Bonjour SDK`.
|
|||
|
|
|
|||
|
|
2. (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/](https://www.msys2.org). Accept the default
|
|||
|
|
installation location `C:\mysys64`.
|
|||
|
|
|
|||
|
|
3. [MSYS2 packages](https://packages.msys2.org/package/) 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).
|
|||
|
|
|
|||
|
|
4. 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](https://gstreamer.freedesktop.org/download/), but only the
|
|||
|
|
MinGW 64-bit build on MSYS2 has been tested.
|
|||
|
|
|
|||
|
|
5. 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 Files\Bonjour SDK`. If it is somewhere
|
|||
|
|
else, set the enviroment variable BONJOUR_SDK_HOME to point to its
|
|||
|
|
location. Then build UxPlay with
|
|||
|
|
|
|||
|
|
`cmake ..`
|
|||
|
|
|
|||
|
|
`ninja`
|
|||
|
|
|
|||
|
|
6. 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
|
|||
|
|
|
|||
|
|
1. **libav**
|
|||
|
|
2. **plugins-good**
|
|||
|
|
3. **plugins-bad**
|
|||
|
|
|
|||
|
|
Other possible MSYS2 gstreamer plugin packages you might use are listed
|
|||
|
|
in [MSYS2 packages](https://packages.msys2.org/package/).
|
|||
|
|
|
|||
|
|
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](https://gstreamer.freedesktop.org/documentation/wasapi/wasapisink.html)
|
|||
|
|
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`.
|
|||
|
|
|
|||
|
|
- With Direct3D 11.0 or greater, you can either always be in
|
|||
|
|
fullscreen mode using option
|
|||
|
|
`-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:\msys64\mingw64\bin\uxplay`.
|
|||
|
|
|
|||
|
|
# Usage
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
|
|||
|
|
- These can also be written (one option per line, without the initial
|
|||
|
|
"`-`" 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 resolution "-s wxh" with h \> 1080 is requested.
|
|||
|
|
The "-h265" option changes the default resolution ("-s" option) from
|
|||
|
|
1920x1080 to 3840x2160, and leaves default maximum framerate ("-fps"
|
|||
|
|
option) at 30fps.
|
|||
|
|
|
|||
|
|
**-hls** 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.
|
|||
|
|
|
|||
|
|
**-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](https://github.com/mikebrady/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 `uxplay` into the foreground, and
|
|||
|
|
terminate it too.
|
|||
|
|
|
|||
|
|
**-reset n** sets a limit of *n* consecutive timeout failures of the
|
|||
|
|
client to respond to ntp requests from the server (these are sent every
|
|||
|
|
3 seconds to check if the client is still present, and synchronize with
|
|||
|
|
it). After *n* failures, the client will be presumed to be offline, and
|
|||
|
|
the connection will be reset to allow a new connection. The default
|
|||
|
|
value of *n* is 5; the value *n* = 0 means "no limit" on timeouts.
|
|||
|
|
|
|||
|
|
**-nofreeze** closes the video window after a reset due to ntp timeout
|
|||
|
|
(default is to leave window open to allow a smoother reconection to the
|
|||
|
|
same client). This option may be useful in fullscreen mode.
|
|||
|
|
|
|||
|
|
**-nc** maintains previous UxPlay \< 1.45 behavior that does **not
|
|||
|
|
close** the video window when the the client sends the "Stop Mirroring"
|
|||
|
|
signal. *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.*
|
|||
|
|
|
|||
|
|
**-nohold** 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.
|
|||
|
|
|
|||
|
|
**-restrict** Restrict clients allowed to connect to those specified by
|
|||
|
|
`-allow <deviceID>`. 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 `XX:XX:XX:XX:XX:XX`, 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.
|
|||
|
|
|
|||
|
|
**-restrict no** Remove restrictions (default). This is useful as a
|
|||
|
|
command-line argument to overide restrictions set in the Startup file.
|
|||
|
|
|
|||
|
|
**-allow *id*** Adds the deviceID = *id* to the list of allowed clients
|
|||
|
|
when client restrictions are being enforced. Usually this will be an
|
|||
|
|
entry in the uxplayrc startup file.
|
|||
|
|
|
|||
|
|
**-block *id*** Always block clients with deviceID = *id*, even when
|
|||
|
|
client restrictions are not being enforced generally. Usually this will
|
|||
|
|
be an entry in the uxplayrc startup file.
|
|||
|
|
|
|||
|
|
**-FPSdata** 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.
|
|||
|
|
|
|||
|
|
**-fps n** 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. *This setting is only an advisory to the client
|
|||
|
|
device, so setting a high value will not force a high framerate.* (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.)
|
|||
|
|
|
|||
|
|
**-f {H\|V\|I}** 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).
|
|||
|
|
|
|||
|
|
**-r {R\|L}** 90 degree Right (clockwise) or Left (counter-clockwise)
|
|||
|
|
rotations; these image transforms are carried out after any **-f**
|
|||
|
|
transforms.
|
|||
|
|
|
|||
|
|
**-m \[mac\]** 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 **-m** was not specified. (Note that a random MAC address will be
|
|||
|
|
different each time UxPlay is started).
|
|||
|
|
|
|||
|
|
**-key \[*filename*\]**: 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
|
|||
|
|
`$HOME/.uxplay.pem`, if that file does not exist, or read from it, if it
|
|||
|
|
exists. (Optionally, the key can be stored in *filename*.) 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 *filename*" (no
|
|||
|
|
initial "-"), where *filename* is a full path which should be enclosed
|
|||
|
|
in quotes (`"...."`) if it contains any blank spaces. **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**.
|
|||
|
|
|
|||
|
|
**-dacp \[*filename*\]**: Export current client DACP-ID and
|
|||
|
|
Active-Remote key to file: default is \$HOME/.uxplay.dacp. (optionally
|
|||
|
|
can be changed to *filename*). Can be used by remote control
|
|||
|
|
applications. File is transient: only exists while client is connected.
|
|||
|
|
|
|||
|
|
**-vdmp** 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 *videodump*, use
|
|||
|
|
-vdmp \[n\] *filename*.
|
|||
|
|
|
|||
|
|
**-admp** 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 *n* restricts the number of packets dumped to a file to *n* or
|
|||
|
|
less. To change the name *audiodump*, use -admp \[n\] *filename*. *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.*
|
|||
|
|
|
|||
|
|
**-d** Enable debug output. Note: this does not show GStreamer error or
|
|||
|
|
debug messages. To see GStreamer error and warning messages, set the
|
|||
|
|
environment variable GST_DEBUG with "export GST_DEBUG=2" before running
|
|||
|
|
uxplay. To see GStreamer information messages, set GST_DEBUG=4; for
|
|||
|
|
DEBUG messages, GST_DEBUG=5; increase this to see even more of the
|
|||
|
|
GStreamer inner workings.
|
|||
|
|
|
|||
|
|
# Troubleshooting
|
|||
|
|
|
|||
|
|
Note: `uxplay` is run from a terminal command line, and informational
|
|||
|
|
messages are written to the terminal.
|
|||
|
|
|
|||
|
|
### 0. Problems in compiling UxPlay.
|
|||
|
|
|
|||
|
|
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
|
|||
|
|
`export OPENSSL_ROOT_DIR=/usr/lib/X86_64-linux-gnu/` before running
|
|||
|
|
cmake.
|
|||
|
|
|
|||
|
|
### 1. **Avahi/DNS_SD Bonjour/Zeroconf issues**
|
|||
|
|
|
|||
|
|
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 `avahi-browse`.
|
|||
|
|
(You may need to install a separate package with a name like
|
|||
|
|
`avahi-utils` to get this.)
|
|||
|
|
|
|||
|
|
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: `sudo systemctl <cmd> avahi-daemon` or
|
|||
|
|
`sudo service avahi-daemon <cmd>`, with `<cmd>` 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
|
|||
|
|
"`sudo find /etc -name avahi-daemon.conf`"): make sure that
|
|||
|
|
"disable-publishing" is **not** 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 [here](https://gist.github.com/reidransom/6033227).)
|
|||
|
|
|
|||
|
|
- **uxplay starts, but either stalls or stops after "Initialized
|
|||
|
|
server socket(s)" appears (*without the server name showing on the
|
|||
|
|
client*)**.
|
|||
|
|
|
|||
|
|
If UxPlay stops with the "No DNS-SD Server found" message, this means
|
|||
|
|
that your network **does not have a running Bonjour/zeroconf DNS-SD
|
|||
|
|
server.** 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: *(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".)* 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
|
|||
|
|
[here](https://github.com/lathiat/avahi/blob/master/avahi-compat-libdns_sd/dns_sd.h).
|
|||
|
|
A few additional error codes are defined in a later version from
|
|||
|
|
[Apple](https://opensource.apple.com/source/mDNSResponder/mDNSResponder-544/mDNSShared/dns_sd.h.auto.html).
|
|||
|
|
|
|||
|
|
If UxPlay stalls *without an error message* and *without the server name
|
|||
|
|
showing on the client*, **this is a network problem** (if your UxPlay
|
|||
|
|
version is older than 1.60, it is also the behavior when no DNS-SD
|
|||
|
|
server is found.)
|
|||
|
|
|
|||
|
|
A useful tool for examining such network problems from the client end is
|
|||
|
|
the (free) Discovery DNS-SD browser [available in the Apple App
|
|||
|
|
Store](https://apps.apple.com/us/developer/lily-ballard/id305441020) for
|
|||
|
|
both iOS (works on iPadOS too) and macOS.
|
|||
|
|
|
|||
|
|
- 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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
- **Avahi works at first, but new clients do not see UxPlay, or
|
|||
|
|
clients that initially saw it stop doing so after they disconnect**.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
To check this, after starting uxplay, use the utility
|
|||
|
|
`avahi-browse -a -t` **in a different terminal window** 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).
|
|||
|
|
|
|||
|
|
The results returned by avahi-browse should show entries for uxplay like
|
|||
|
|
|
|||
|
|
+ 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
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
### 2. uxplay starts, but stalls after "Initialized server socket(s)" appears, *with the server name showing on the client* (but the client fails to connect when the UxPlay server is selected).
|
|||
|
|
|
|||
|
|
This shows that a *DNS-SD* 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 *two* active
|
|||
|
|
firewalls (*firewalld* and *ufw*) *both* 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").
|
|||
|
|
|
|||
|
|
If you are *really* 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.
|
|||
|
|
|
|||
|
|
### 3. Problems *after* the client-server connection has been made:
|
|||
|
|
|
|||
|
|
If you do *not* see the message `raop_rtp_mirror starting mirroring`,
|
|||
|
|
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 [UxPlay
|
|||
|
|
Wiki](https://github.com/FDH2/UxPlay/wiki).
|
|||
|
|
|
|||
|
|
**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** (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: **three** are
|
|||
|
|
required (the third one receives the audio data).
|
|||
|
|
|
|||
|
|
**Raspberry Pi** devices (*Pi 4B+ and earlier: this does not apply to
|
|||
|
|
the Pi 5, which does not provide hardware h264 decoding, and does not
|
|||
|
|
need it*) 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
|
|||
|
|
[Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
|
|||
|
|
for patches). This is fixed in GStreamer-1.22, and by backport patches
|
|||
|
|
from this in distributions such as Raspberry Pi OS (Bullseye): **use
|
|||
|
|
option `-bt709` with the GStreamer-1.18.4 from Raspberry Pi OS**. 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).
|
|||
|
|
|
|||
|
|
- **If this kernel module is not available in your Raspberry Pi
|
|||
|
|
operating system, or if GStreamer \< 1.22 is not patched, use option
|
|||
|
|
`-avdec` for software h264-decoding.**
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.)
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
If you *do* have Intel HD graphics, and have installed the vaapi plugin,
|
|||
|
|
but `-vs vaapisink` does not work, check that vaapi is not "blacklisted"
|
|||
|
|
in your GStreamer installation: run `gst-inspect-1.0 vaapi`, if this
|
|||
|
|
reports `0 features`, you need to `export GST_VAAPI_ALL_DRIVERS=1`
|
|||
|
|
before running uxplay, or set this in the default environment.
|
|||
|
|
|
|||
|
|
You can try to fix audio or video problems by using the
|
|||
|
|
"`-as <audiosink>`" or "`-vs <videosink>`" options to choose the
|
|||
|
|
GStreamer audiosink or videosink , rather than letting GStreamer choose
|
|||
|
|
one for you. (See above, in [Starting and running
|
|||
|
|
UxPlay](#starting-and-running-uxplay) for choices of `<audiosink>` or
|
|||
|
|
`<videosink>`.)
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
### 4. GStreamer issues (missing plugins, etc.):
|
|||
|
|
|
|||
|
|
- clearing the user's GStreamer cache with
|
|||
|
|
`rm -rf ~/.cache/gstreamer-1.0/*` 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. **This is the solution to puzzling problems that turn out
|
|||
|
|
to come from corruption of the cache, and should be tried first.**
|
|||
|
|
|
|||
|
|
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, *e.g.* a libav problem, check with
|
|||
|
|
"`gst-inspect-1.0 libav`". 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 "**Required gstreamer plugin 'libav' not
|
|||
|
|
found**" message that kept recurring was to clear the user's gstreamer
|
|||
|
|
cache.
|
|||
|
|
|
|||
|
|
If it fails to start with an error like '`no element "avdec_aac"`' this
|
|||
|
|
is because even though gstreamer-libav is installed. it is incomplete
|
|||
|
|
because some plugin features are missing:
|
|||
|
|
"`gst-inspect-1.0 | grep avdec_aac`" will show if avdec_aac is
|
|||
|
|
available. Unlike other GStreamer plugins, the libav plugin is a front
|
|||
|
|
end to FFmpeg codecs which provide avdec\_\*.
|
|||
|
|
|
|||
|
|
- 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 [RPM fusion](https://rpmfusion.org) (RedHat),
|
|||
|
|
[packman](http://packman.links2linux.org/) (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: *"Adding --allowerasing to
|
|||
|
|
the dnf command fixed it after a restart"*.
|
|||
|
|
|
|||
|
|
- starting with release UxPlay-1.65.3, UxPlay will continue to
|
|||
|
|
function, but without audio in mirror mode, if avdec_aac is missing.
|
|||
|
|
|
|||
|
|
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
|
|||
|
|
[GStreamer debugging
|
|||
|
|
tools](https://gstreamer.freedesktop.org/documentation/tutorials/basic/debugging-tools.html)
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
The GStreamer video pipeline, which is shown in the initial output from
|
|||
|
|
`uxplay -d`, has the default form
|
|||
|
|
|
|||
|
|
appsrc name=video_source ! queue ! h264parse ! decodebin ! videoconvert ! autovideosink name=video_sink sync=false
|
|||
|
|
|
|||
|
|
The pipeline is fully configurable: default elements "h264parse",
|
|||
|
|
"decodebin", "videoconvert", and "autovideosink" can respectively be
|
|||
|
|
replaced by using uxplay options `-vp`, `-vd`, `-vc`, and `-vs`, if
|
|||
|
|
there is any need to modify it (entries can be given in quotes "..." to
|
|||
|
|
include options).
|
|||
|
|
|
|||
|
|
### 5. Mirror screen freezes (a network problem):
|
|||
|
|
|
|||
|
|
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 *n*", where *n* is the desired
|
|||
|
|
timeout-limit value (*n* = 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.
|
|||
|
|
|
|||
|
|
- When the connection is reset, the "frozen" mirror screen of the
|
|||
|
|
previous connection is left in place, but does **not** block new
|
|||
|
|
connections, and will be taken over by a new client connection when
|
|||
|
|
it is made.
|
|||
|
|
|
|||
|
|
### 6. Protocol issues (with decryption of the encrypted audio and video streams sent by the client).
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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). **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.** ("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.)
|
|||
|
|
|
|||
|
|
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 *AirMyPC*, the
|
|||
|
|
protocol can be switched to the older version by the setting
|
|||
|
|
`OLD_PROTOCOL_CLIENT_USER_AGENT_LIST` in `UxPlay/lib/global.h`. UxPlay
|
|||
|
|
reports the client's "User Agent" string when it connects. If some other
|
|||
|
|
client also fails to decrypt all audio and video, try adding its "User
|
|||
|
|
Agent" string in place of "xxx" in the entry "AirMyPC/2.0;xxx" in
|
|||
|
|
global.h and rebuild uxplay.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
# Changelog
|
|||
|
|
|
|||
|
|
1.71 2024-12-13 Add support for HTTP Live Streaming (HLS), initially
|
|||
|
|
only for YouTube movies. Fix issue with NTP timeout on Windows.
|
|||
|
|
|
|||
|
|
1.70 2024-10-04 Add support for 4K (h265) video (resolution 3840 x
|
|||
|
|
2160). Fix issue with GStreamer \>= 1.24 when client sleeps, then wakes.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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).
|
|||
|
|
|
|||
|
|
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 @thiccaxe
|
|||
|
|
(screen lag in vsync mode after client wakes from sleep).
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
1.65 2023-06-03 Eliminate pair_setup part of connection protocol to
|
|||
|
|
allow faster connections with clients (thanks to @shuax #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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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
|
|||
|
|
|
|||
|
|
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).
|
|||
|
|
|
|||
|
|
1.59 2022-12-12 remove "ZOOMFIX" compile option and make compilation
|
|||
|
|
with X11-dependence the default if X11 development libraries are
|
|||
|
|
detected (this now also provides fullscreen mode with a F11 or Alt+Enter
|
|||
|
|
key toggle); ZOOMFIX is now automatically applied for GStreamer \< 1.20.
|
|||
|
|
New cmake option -DNO_X11_DEPS compiles uxplay without X11 dependence.
|
|||
|
|
Reworked internal metadata handling. Fix segfault with "-vs 0".
|
|||
|
|
|
|||
|
|
1.58 2022-10-29 Add option "-nohold" that will drop existing connections
|
|||
|
|
when a new client connects. Update llhttp to v8.1.0.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
1.56 2022-09-01 Added support for building and running UxPlay-1.56 on
|
|||
|
|
Windows (no changes to Unix (Linux, \*BSD, macOS) codebase.)
|
|||
|
|
|
|||
|
|
1.56 2022-07-30 Remove -bt709 from -rpi, -rpiwl, -rpifb as GStreamer is
|
|||
|
|
now fixed.
|
|||
|
|
|
|||
|
|
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).
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
1.53 2022-06-13 Internal changes to audio sync code, revised
|
|||
|
|
documentation, Minor bugfix (fix assertion crash when resent audio
|
|||
|
|
packets are empty).
|
|||
|
|
|
|||
|
|
1.52 2022-05-05 Cleaned up initial audio sync code, and reformatted
|
|||
|
|
streaming debug output (readable aligned timestamps with decimal points
|
|||
|
|
in seconds). Eliminate memory leaks (found by valgrind). Support for
|
|||
|
|
display of ALAC (audio-only) metadata (soundtrack artist names, titles
|
|||
|
|
etc.) in the uxplay terminal.
|
|||
|
|
|
|||
|
|
1.51 2022-04-24 Reworked options forVideo4Linux2 support (new option
|
|||
|
|
-v4l2) and short options -rpi, -rpifb, -rpiwl as synonyms for -v4l2,
|
|||
|
|
-v4l2 -vs kmssink, and -v4l2 -vs waylandsink. Reverted a change from
|
|||
|
|
1.48 that broke reconnection after "Stop Mirroring" is sent by client.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
1.48 2022-03-11 Made the GStreamer video pipeline fully configurable,
|
|||
|
|
for use with hardware h264 decoding. Support for Raspberry Pi.
|
|||
|
|
|
|||
|
|
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).
|
|||
|
|
|
|||
|
|
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).
|
|||
|
|
|
|||
|
|
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).
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
1.43 2021-12-07 Various internal changes, such as tests for successful
|
|||
|
|
decryption, uniform treatment of informational/debug messages, etc.,
|
|||
|
|
updated README.
|
|||
|
|
|
|||
|
|
1.42 2021-11-20 Fix MAC detection to work with modern Linux interface
|
|||
|
|
naming practices, MacOS and \*BSD.
|
|||
|
|
|
|||
|
|
1.41 2021-11-11 Further cleanups of multiple audio format support
|
|||
|
|
(internal changes, separated RAOP and GStreamer audio/video startup)
|
|||
|
|
|
|||
|
|
1.40 2021-11-09 Cleanup segfault in ALAC support, manpage location fix,
|
|||
|
|
show request Plists in debug mode.
|
|||
|
|
|
|||
|
|
1.39 2021-11-06 Added support for Apple Lossless (ALAC) audio streams.
|
|||
|
|
|
|||
|
|
1.38 2021-10-8 Add -as *audiosink* option to allow user to choose the
|
|||
|
|
GStreamer audiosink.
|
|||
|
|
|
|||
|
|
1.37 2021-09-29 Append "@hostname" to AirPlay Server name, where
|
|||
|
|
"hostname" is the name of the server running uxplay (reworked change in
|
|||
|
|
1.36).
|
|||
|
|
|
|||
|
|
1.36 2021-09-29 Implemented suggestion (by @mrbesen and @PetrusZ) to use
|
|||
|
|
hostname of machine runing uxplay as the default server name
|
|||
|
|
|
|||
|
|
1.35.1 2021-09-28 Added the -vs 0 option for streaming audio, but not
|
|||
|
|
displaying video.
|
|||
|
|
|
|||
|
|
1.35 2021-09-10 now uses a GLib MainLoop, and builds on macOS (tested on
|
|||
|
|
Intel Mac, 10.15 ). New option -t *timeout* for relaunching server if no
|
|||
|
|
connections were active in previous *timeout* seconds (to renew Bonjour
|
|||
|
|
registration).
|
|||
|
|
|
|||
|
|
1.341 2021-09-04 fixed: render logger was not being destroyed by
|
|||
|
|
stop_server()
|
|||
|
|
|
|||
|
|
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
|
|||
|
|
|
|||
|
|
### Building OpenSSL \>= 1.1.1 from source.
|
|||
|
|
|
|||
|
|
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
|
|||
|
|
<https://www.openssl.org/source/>. 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 `libcrypto.*`, either in
|
|||
|
|
/usr/local/lib or /usr/local/lib64.
|
|||
|
|
|
|||
|
|
*(Ignore the following for builds on MacOS:)* On some systems like
|
|||
|
|
Debian or Ubuntu, you may also need to add a missing entry
|
|||
|
|
`/usr/local/lib64` 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".
|
|||
|
|
|
|||
|
|
### Building libplist \>= 2.0.0 from source.
|
|||
|
|
|
|||
|
|
*(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.)* 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
|
|||
|
|
<https://github.com/libimobiledevice/libplist>, or get the source from
|
|||
|
|
the Releases section (use the \*.tar.bz2 release, **not** the \*.zip or
|
|||
|
|
\*.tar.gz versions): download
|
|||
|
|
[libplist-2.3.0](https://github.com/libimobiledevice/libplist/releases/download/2.3.0/libplist-2.3.0.tar.bz2),
|
|||
|
|
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;
|
|||
|
|
[libplist-2.2.0](https://github.com/libimobiledevice/libplist/releases/download/2.2.0/libplist-2.2.0.tar.bz2)
|
|||
|
|
is also available if there are any issues.
|
|||
|
|
|
|||
|
|
*(Ignore the following for builds on MacOS:)* On some systems like
|
|||
|
|
Debian or Ubuntu, you may also need to add a missing entry
|
|||
|
|
`/usr/local/lib` 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".
|
|||
|
|
|
|||
|
|
# Disclaimer
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
# UxPlay authors
|
|||
|
|
|
|||
|
|
*\[adapted from fdraschbacher's notes on RPiPlay antecedents\]*
|
|||
|
|
|
|||
|
|
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:
|
|||
|
|
|
|||
|
|
UxPlay was initially created by **antimof** 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 `renderers/` was later backported to RPiPlay, and the antimof project
|
|||
|
|
became dormant, but was later revived at the [current GitHub
|
|||
|
|
site](http://github.com/FDH2/UxPlay) to serve a wider community of
|
|||
|
|
users.
|
|||
|
|
|
|||
|
|
The previous authors of code included in UxPlay by inheritance from
|
|||
|
|
RPiPlay include:
|
|||
|
|
|
|||
|
|
- **EstebanKubata**: Created a FairPlay library called
|
|||
|
|
[PlayFair](https://github.com/EstebanKubata/playfair). Located in
|
|||
|
|
the `lib/playfair` folder. License: GNU GPL
|
|||
|
|
- **Juho Vähä-Herttua** and contributors: Created an AirPlay audio
|
|||
|
|
server called [ShairPlay](https://github.com/juhovh/shairplay),
|
|||
|
|
including support for Fairplay based on PlayFair. Most of the code
|
|||
|
|
in `lib/` originally stems from this project. License: GNU LGPLv2.1+
|
|||
|
|
- **dsafa22**: Created an AirPlay 2 mirroring server
|
|||
|
|
[AirplayServer](https://github.com/dsafa22/AirplayServer) (seems
|
|||
|
|
gone now), for Android based on ShairPlay. Code is preserved
|
|||
|
|
[here](https://github.com/jiangban/AirplayServer), and [see
|
|||
|
|
here](https://github.com/FDH2/UxPlay/wiki/AirPlay2) for the
|
|||
|
|
description of the analysis of the AirPlay 2 mirror protocol that
|
|||
|
|
made RPiPlay possible, by the AirplayServer author. All code in
|
|||
|
|
`lib/` concerning mirroring is dsafa22's work. License: GNU
|
|||
|
|
LGPLv2.1+
|
|||
|
|
- **Florian Draschbacher** (FD-) and contributors: adapted dsafa22's
|
|||
|
|
Android project for the Raspberry Pi, with extensive cleanups,
|
|||
|
|
debugging and improvements. The project
|
|||
|
|
[RPiPlay](https://github.com/FD-/RPiPlay) 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 [Airplay protocol
|
|||
|
|
versions](http://github.com/FD-/RPiPlay#airplay-protocol-versions),
|
|||
|
|
available at the RPiPlay github repository.
|
|||
|
|
|
|||
|
|
Independent of UxPlay, but used by it and bundled with it:
|
|||
|
|
|
|||
|
|
- **Fedor Indutny** (of Node.js, and formerly Joyent, Inc) and
|
|||
|
|
contributors: Created an http parsing library called
|
|||
|
|
[llhttp](https://github.com/nodejs/llhttp). Located at
|
|||
|
|
`lib/llhttp/`. License: MIT
|