morgan/UxPlay
1
0
Fork 0
mirror of https://github.com/morgan9e/UxPlay synced 2026-04-14 00:04:13 +09:00
Code Issues Packages Projects Releases Wiki Activity

iPod Touch gen 5 and later is supported; iOS 16 supports UxPlay

Browse Source
This commit is contained in:
fduncanh
2022-09-21 14:27:28 -04:00
parent 104b92f2ee
commit 94f414346c
3 changed files with 161 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
README.html
View File

@@ -12,28 +12,28 @@ href="https://github.com/FDH2/UxPlay">https://github.com/FDH2/UxPlay</a>
<li><p>GPLv3, open source.</p></li>
<li><p>Originally supported only AirPlay Mirror protocol, now has added
support for AirPlay Audio-only (Apple Lossless ALAC) streaming from
current iOS/iPadOS 15.6 clients. <strong>There is no support for
Airplay2 video-streaming protocol, and none is
planned.</strong></p></li>
current iOS/iPadOS clients. <strong>There is no support for Airplay2
video-streaming protocol, and none is planned.</strong></p></li>
<li><p>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.</p></li>
<li><p>Support for older iOS clients (such as 32-bit iPad 2nd gen. and
iPhone 4S, when upgraded to iOS 9.3.5 or later), plus a Windows
AirPlay-client emulator, AirMyPC.</p></li>
<li><p>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 versions), plus a Windows AirPlay-client emulator,
AirMyPC.</p></li>
<li><p>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).</p></li>
<li><p>Support for server behind a firewall.</p></li>
<li><p><strong>New</strong>: Support for Raspberry Pi, with hardware
video acceleration using Video4Linux2 (vl42), which supports both 32-
and 64-bit systems, unlike deprecated OpenMAX (omx), which is being
dropped by RPi distributions in favor of v4l2. (For GStreamer &lt; 1.22,
a backport of changes from the GStreamer development branch is needed:
this has now been done by Raspberry Pi OS (Bullseye); for other
distributions a <a
video acceleration using Video4Linux2 (v4l2), which supports both 32-
and 64-bit systems: this is the replacement for 32-bit-only OpenMAX
(omx), for which support by RPi distributions is being discontinued.
(Until GStreamer 1.22 is released, a backport of changes from the
GStreamer development branch is needed: this has now been done by
Raspberry Pi OS (Bullseye); for other distributions a <a
href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patch</a>
to the GStreamer Video4Linux2 plugin, available in the <a
href="https://github.com/FDH2/UxPlay/wiki">UxPlay Wiki</a>, is
@@ -41,8 +41,8 @@ required.) See <a
href="https://github.com/FDH2/UxPlay/wiki/UxPlay-on-Raspberry-Pi:-success-reports:">success
reports</a>.</p></li>
<li><p><strong>New</strong>: Support for running on Microsoft Windows
(so far only tested on current Windows 10 64 bit, using MinGW-64
compiler in MSYS2 environment).</p></li>
(builds with the MinGW-64 compiler in the unix-like MSYS2
environment).</p></li>
</ul>
<p>This project is a GPLv3 open source unix AirPlay2 Mirror server for
Linux, macOS, and *BSD. It was initially developed by <a
@@ -60,17 +60,21 @@ Debian 10.11 “Buster” and 11.2 “Bullseye”, Ubuntu 20.04 and 22.04, Linux
Mint 20.3, Pop!_OS 22.04 (NVIDIA edition), Rocky Linux 8.6 (a CentOS
successor), OpenSUSE 15.4, Arch Linux 5.16.8, macOS 12.3 (Intel and M1),
FreeBSD 13.1. On Raspberry Pi, it is tested on Raspberry Pi OS
(Bullseye) (32- and 64-bit), Ubuntu 22.04, and Manjaro RPi4 22.04.</p>
(Bullseye) (32- and 64-bit), Ubuntu 22.04, and Manjaro RPi4 22.04. Also
tested on 64-bit Windows 10 and 11.</p>
<p>Its main use is to act like an AppleTV for screen-mirroring (with
audio) of iOS/iPadOS/macOS clients (iPhones, iPads, MacBooks) in a
window on the server display (with the possibility of sharing that
window on screen-sharing applications such as Zoom) on a host running
Linux, macOS, or other unix. UxPlay supports Apple’s AirPlay2 protocol
using “Legacy Pairing”, but some features are missing. (Details of what
is publically known about Apple’s AirPlay 2 protocol can be found <a
audio) of iOS/iPadOS/macOS clients (iPhone, iPod Touch, iPad, Mac
computers) in a window on the server display (with the possibility of
sharing that window on screen-sharing applications such as Zoom) on a
host running Linux, macOS, or other unix (and now also Microsoft
Windows). UxPlay supports Apple’s AirPlay2 protocol using “Legacy
Pairing”, but some features are missing. (Details of what is publically
known about Apple’s AirPlay 2 protocol can be found <a
href="https://openairplay.github.io/airplay-spec/">here</a>, <a
href="https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol">here</a>
and <a href="https://emanuelecozzi.net/docs/airplay2">here</a>).</p>
and <a href="https://emanuelecozzi.net/docs/airplay2">here</a>). While
there is no guarantee that future iOS releases will keep supporting
“Legacy Pairing”, the recent iOS 16 release continues support.</p>
<p>The UxPlay server and its client must be on the same local area
network, on which a <strong>Bonjour/Zeroconf mDNS/DNS-SD server</strong>
is also running (only DNS-SD “Service Discovery” service is strictly
@@ -89,10 +93,7 @@ Lossless (ALAC) audio without screen mirroring. In
terminal; if UxPlay option <code>-ca &lt;name&gt;</code> is used, the
accompanying cover art is also output to a periodically-updated file
<code>&lt;name&gt;</code>, and can be viewed with a (reloading) graphics
viewer of your choice such as <code>feh</code>: run
“<code>uxplay -ca &lt;name&gt; &amp;</code>” in the background, then run
“<code>feh -R 1 &lt;name&gt;</code>” in the foreground; terminate with
“<code>ctrl-C fg ctrl-C</code>”. <em>Switching between</em>
viewer of your choice. <em>Switching between</em>
<strong>Mirror</strong> <em>and</em> <strong>Audio</strong> <em>modes
during an active connection is possible: in</em> <strong>Mirror</strong>
<em>mode, stop mirroring (or close the mirror window) and start an</em>
@@ -110,8 +111,8 @@ UxPlay in Mirror mode.</strong></p></li>
<li><p><strong>As UxPlay does not support non-Mirror AirPlay2 video
streaming (where the client controls a web server on the AirPlay server
that directly receives content to avoid it being decoded and re-encoded
by the client), using the icon for AirPlay video in apps such as the You
Tube app will only send audio (in lossless ALAC format) without the
by the client), using the icon for AirPlay video in apps such as the
YouTube app will only send audio (in lossless ALAC format) without the
accompanying video.</strong></p></li>
</ul>
<h3
@@ -288,6 +289,12 @@ prevents UxPlay from receiving client connection requests unless some
network ports are opened. See <a
href="#troubleshooting">Troubleshooting</a> below for help with this or
other problems.</p>
<p>To display the accompanying “Cover Art” from sources like Apple Music
in Audio-Only (ALAC) mode, run
“<code>uxplay -ca &lt;name&gt; &amp;</code>” in the background, then run
a image viewer with an autoreload feature: an example is “feh”: run
“<code>feh -R 1 &lt;name&gt;</code>” in the foreground; terminate feh
and then Uxplay with “<code>ctrl-C fg ctrl-C</code>”.</p>
<p><strong>One common problem involves GStreamer attempting to use
incorrectly-configured or absent accelerated hardware h264 video
decoding (e.g., VAAPI). Try “<code>uxplay -avdec</code>” to force
@@ -320,9 +327,10 @@ the Wayland video compositor, use <code>&lt;videosink&gt;</code> =
<code>waylandsink</code>. For convenience, these options are also
available combined in options <code>-rpi</code>, <code>-rpigl</code>
<code>-rpifb</code>, <code>-rpiwl</code>, respectively provided for X11,
X11 with OpenGL, framebuffer, and Wayland systems. You may find the
simple “uxplay”, (which lets GStreamer try to find the best video
solution by itself) provides the best results.</p>
X11 with OpenGL, framebuffer, and Wayland systems. You may find that
just “<code>uxplay</code>”, (<em>without</em> <code>-v4l2</code> or
<code>-rpi*</code> options, which lets GStreamer try to find the best
video solution by itself) provides the best results.</p>
<ul>
<li><p><strong>For UxPlay-1.56 and later, if you are not using the
latest GStreamer patches from the Wiki, you will need to use the UxPlay
@@ -333,7 +341,7 @@ GStreamer-1.20.4 will have a fix for this, which is included in the
latest patches, so beginning with UxPlay-1.56, the bt709 fix is no
longer automatically applied. <strong>After a recent update, Raspberry
Pi OS (Bullseye) now supplies an already-patched GStreamer-1.18.4 that
can run UxPlay, but needs the <code>-bt709</code> option with
works with UxPlay, but needs the <code>-bt709</code> option with
UxPlay-1.56 or later.</strong></p></li>
<li><p>Tip: to start UxPlay on a remote host (such as a Raspberry Pi)
using ssh:</p></li>
@@ -461,9 +469,12 @@ from the initial “-s wxh” setting (also use the iPad/iPhone setting that
locks the screen orientation against switching between portrait and
landscape mode as the device is rotated).</p>
<h2
id="building-uxplay-on-windows-tested-on-windows-10-64bit-using-msys2-and-mingw-64-compiler">Building
UxPlay on Windows (tested on Windows 10 64bit, using MSYS2 and MinGW-64
compiler)</h2>
id="building-uxplay-on-microsoft-windows-using-msys2-with-the-mingw-64-compiler.">Building
UxPlay on Microsoft Windows, using MSYS2 with the MinGW-64
compiler.</h2>
<ul>
<li>tested on Windows 10 and 11, 64-bit.</li>
</ul>
<ol type="1">
<li><p>Download and install <strong>Bonjour SDK for Windows
v3.0</strong> from the official Apple site <a
@@ -546,7 +557,9 @@ by its GUID, which can be found using
has a form like
<code>\{0.0.0.00000000\}.\{98e35b2b-8eba-412e-b840-fd2c2492cf44\}</code>.
If “<code>device</code>” is not specified, the default audio device is
used.</p>
used. The executable uxplay.exe can also be run without the MSYS2
environment (using the Windows Terminal, with
<code>C:\msys64\mingw64\bin\uxplay</code>).</p>
<h1 id="usage">Usage</h1>
<p>Options:</p>
<p><strong>-n server_name</strong> (Default: UxPlay);
@@ -665,12 +678,13 @@ then run the the image viewer in the foreground. Example, using
in which uxplay was put into the background). To quit, use
<code>ctrl-C fg ctrl-C</code> to terminate the image viewer, bring
<code>uxplay</code> into the foreground, and terminate it too.</p>
<p><strong>-reset n</strong> sets a limit of 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). 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.</p>
<p><strong>-reset n</strong> sets a limit of <em>n</em> consecutive
timeout failures of the client to respond to ntp requests from the
server (these are sent every 3 seconds to check if the client is still
present, and synchronize with it). After <em>n</em> failures, the client
will be presumed to be offline, and the connection will be reset to
allow a new connection. The default value of <em>n</em> is 5; the value
<em>n</em> = 0 means “no limit” on timeouts.</p>
<p><strong>-nc</strong> maintains previous UxPlay &lt; 1.45 behavior
that does <strong>not close</strong> the video window when the the
client sends the “Stop Mirroring” signal. <em>This option is currently
@@ -726,7 +740,9 @@ format audio), audiodump.x.alac (ALAC format audio) or audiodump.x.aud
(other-format audio), where x = 1,2,3… increases each time the audio
format changes. -admp <em>n</em> restricts the number of packets dumped
to a file to <em>n</em> or less. To change the name <em>audiodump</em>,
use -admp [n] <em>filename</em>.</p>
use -admp [n] <em>filename</em>. <em>Note that (unlike dumped video) the
dumped audio is currently only useful for debugging, as it is not
containerized to make it playable with standard audio players.</em></p>
<p><strong>-d</strong> Enable debug output. Note: this does not show
GStreamer error or debug messages. To see GStreamer error and warning
messages, set the environment variable GST_DEBUG with “export
@@ -797,7 +813,10 @@ Wiki</a>.</p>
video or audio, the problem is probably from a GStreamer plugin that
doesn’t work on your system</strong> (by default, GStreamer uses the
“autovideosink” and “autoaudiosink” algorithms to guess what are the
“best” plugins to use on your system).</p>
“best” plugins to use on your system). A different reason for no audio
occurred when a user with a firewall only opened two udp network ports:
<strong>three</strong> are required (the third one receives the audio
data).</p>
<p><strong>Raspberry Pi</strong> devices (-rpi option) only work with
hardware GPU decoding if the Video4Linux2 plugin in GStreamer v1.20.x or
earlier has been patched (see the UxPlay <a
@@ -929,8 +948,7 @@ the client by the AirPlay server) to be set. The “features” code and
other settings are set in <code>UxPlay/lib/dnssdint.h</code>.</p>
<h1 id="changelog">Changelog</h1>
<p>1.56 2022-09-01 Added support for building and running UxPlay-1.56 on
Windows (github source only, no changes to Unix (Linux, *BSD, macOS)
codebase.)</p>
Windows (no changes to Unix (Linux, *BSD, macOS) codebase.)</p>
<p>1.56 2022-07-30 Remove -bt709 from -rpi, -rpiwl, -rpifb as GStreamer
is now fixed.</p>
<p>1.55 2022-07-04 Remove the bt709 fix from -v4l2 and create a new

63
README.md
View File

@@ -8,30 +8,30 @@ 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 15.6 clients. **There is no support for Airplay2 video-streaming protocol, and none is planned.**
from current iOS/iPadOS clients. **There is no support for Airplay2 video-streaming protocol, and none is planned.**
* 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. and
iPhone 4S, when upgraded to iOS 9.3.5 or later), plus a
* 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 versions), 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.
* **New**: Support for Raspberry Pi, with hardware video acceleration using
Video4Linux2 (vl42), which supports both 32- and 64-bit systems, unlike deprecated
OpenMAX (omx), which is being dropped by RPi distributions in favor of v4l2. (For GStreamer < 1.22,
a backport of changes from the GStreamer development branch is needed: this has now been done
Video4Linux2 (v4l2), which supports both 32- and 64-bit systems: this is the replacement for
32-bit-only OpenMAX (omx), for which support by RPi distributions is being discontinued. (Until GStreamer 1.22
is released, a backport of changes from the GStreamer development branch is needed: this has now been done
by Raspberry Pi OS (Bullseye); for other distributions
a [patch](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
to the GStreamer Video4Linux2 plugin, available in the
[UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki), is required.)
See [success reports](https://github.com/FDH2/UxPlay/wiki/UxPlay-on-Raspberry-Pi:-success-reports:).
* **New**: Support for running on Microsoft Windows (so far only tested on current Windows 10 64 bit,
using MinGW-64 compiler in MSYS2 environment).
* **New**: Support for running on Microsoft Windows (builds with the MinGW-64 compiler in the
unix-like MSYS2 environment).
This project is a GPLv3 open source unix AirPlay2 Mirror server for Linux, macOS, and \*BSD.
It was initially developed by
@@ -47,17 +47,19 @@ UxPlay is tested on a number of systems, including (among others) Debian 10.11 "
Ubuntu 20.04 and 22.04, Linux Mint 20.3, Pop!\_OS 22.04 (NVIDIA edition), Rocky Linux 8.6 (a CentOS successor),
OpenSUSE 15.4, Arch Linux 5.16.8, macOS 12.3 (Intel and M1), FreeBSD 13.1.
On Raspberry Pi, it is tested on Raspberry Pi OS (Bullseye) (32- and 64-bit), Ubuntu 22.04, and Manjaro RPi4 22.04.
Also tested on 64-bit Windows 10 and 11.
Its main use is to act like an AppleTV for screen-mirroring (with audio) of iOS/iPadOS/macOS clients
(iPhones, iPads, MacBooks) in a window
(iPhone, iPod Touch, iPad, Mac computers) in a window
on the server display (with the possibility of
sharing that window on screen-sharing applications such as Zoom)
on a host running Linux, macOS, or other unix. UxPlay supports Apple's AirPlay2
protocol using "Legacy Pairing", but some features are missing.
on a host running Linux, macOS, or other unix (and now also Microsoft Windows). UxPlay supports
Apple's AirPlay2 protocol using "Legacy Pairing", but some features are missing.
(Details of what is publically 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)).
[here](https://emanuelecozzi.net/docs/airplay2)). While there is no guarantee that future
iOS releases will keep supporting "Legacy Pairing", the recent iOS 16 release 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
@@ -76,9 +78,7 @@ 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 such as `feh`:
run "`uxplay -ca <name> &`" in the background, then run "``feh -R 1 <name>``"
in the foreground; terminate with "`ctrl-C fg ctrl-C`".
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._
@@ -91,7 +91,7 @@ but both video and audio content from DRM-free apps like "YouTube app" will be
* **As UxPlay does not support non-Mirror AirPlay2 video streaming (where the
client controls a web server on the AirPlay server that directly receives
content to avoid it being decoded and re-encoded by the client),
using the icon for AirPlay video in apps such as the You Tube app
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 video-decoding, if available.
@@ -246,6 +246,12 @@ UxPlay from receiving client connection requests unless some network ports
are opened. See [Troubleshooting](#troubleshooting) below for
help with this or other problems.
To 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`".
**One common problem involves GStreamer
attempting to use incorrectly-configured or absent accelerated hardware h264
video decoding (e.g., VAAPI).
@@ -270,14 +276,14 @@ On a system without X11 (like R Pi OS Lite) with framebuffer video, use `<videos
With the Wayland video compositor, use `<videosink>` = ``waylandsink``. For convenience,
these options are also available combined in options `-rpi`, ``-rpigl``
``-rpifb``, ```-rpiwl```, respectively provided for X11, X11 with OpenGL, framebuffer, and Wayland systems.
You may find the simple "uxplay", (which lets GStreamer try to find the best video solution by itself)
You may find that just "`uxplay`", (_without_ ``-v4l2`` or ```-rpi*``` options, which lets GStreamer try to find the best video solution by itself)
provides the best results.
* **For UxPlay-1.56 and later, if you are not using the latest GStreamer patches from the Wiki, you will need to use the UxPlay option `-bt709`**:
previously the GStreamer v4l2 plugin could
not recognise Apple's color format (an unusual "full-range" variant of the bt709 HDTV standard), which -bt709 fixes. GStreamer-1.20.4 will have
a fix for this, which is included in the latest patches, so beginning with UxPlay-1.56, the bt709 fix is no longer automatically applied.
**After a recent update, Raspberry Pi OS (Bullseye) now supplies an already-patched GStreamer-1.18.4 that can run UxPlay, but
**After a recent update, Raspberry Pi OS (Bullseye) now supplies an already-patched GStreamer-1.18.4 that works with UxPlay, but
needs the `-bt709` option with UxPlay-1.56 or later.**
@@ -385,8 +391,9 @@ Using the MacPorts X11 GStreamer seems only possible if the image size is left u
(also use the iPad/iPhone setting that locks the screen orientation against switching between portrait and landscape mode
as the device is rotated).
## Building UxPlay on Windows (tested on Windows 10 64bit, using MSYS2 and MinGW-64 compiler)
## 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** from the official Apple site
[https://developer.apple.com/download](https://developer.apple.com/download/all/?q=Bonjour%20SDK%20for%20Windows)
@@ -462,7 +469,8 @@ uxplay -as 'wasapisink low_latency=true 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.
default audio device is used. The executable uxplay.exe can also be run without the MSYS2 environment (using
the Windows Terminal, with `C:\msys64\mingw64\bin\uxplay`).
# Usage
@@ -573,10 +581,10 @@ which will not work if a firewall is running.
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). 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.
**-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.
**-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,
@@ -627,7 +635,8 @@ which will not work if a firewall is running.
**-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_.
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.
@@ -682,6 +691,8 @@ that from a successful start of UxPlay in the [UxPlay Wiki](https://github.com/F
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 (-rpi option) only work with hardware GPU 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).
@@ -789,7 +800,7 @@ tvOS 12.2.1); it seems that the use of "legacy" protocol just requires bit 27 (l
The "features" code and other settings are set in `UxPlay/lib/dnssdint.h`.
# Changelog
1.56 2022-09-01 Added support for building and running UxPlay-1.56 on Windows (github source only, no changes
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.

105
README.txt
View File

@@ -8,7 +8,7 @@ Highlights:
- Originally supported only AirPlay Mirror protocol, now has added
support for AirPlay Audio-only (Apple Lossless ALAC) streaming from
current iOS/iPadOS 15.6 clients. **There is no support for Airplay2
current iOS/iPadOS clients. **There is no support for Airplay2
video-streaming protocol, and none is planned.**
- macOS computers (2011 or later, both Intel and "Apple Silicon" M1/M2
@@ -16,9 +16,9 @@ Highlights:
UxPlay. Using AirPlay, UxPlay can emulate a second display for macOS
clients.
- Support for older iOS clients (such as 32-bit iPad 2nd gen. and
iPhone 4S, when upgraded to iOS 9.3.5 or later), plus a Windows
AirPlay-client emulator, AirMyPC.
- 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 versions), 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
@@ -28,21 +28,20 @@ Highlights:
- Support for server behind a firewall.
- **New**: Support for Raspberry Pi, with hardware video acceleration
using Video4Linux2 (vl42), which supports both 32- and 64-bit
systems, unlike deprecated OpenMAX (omx), which is being dropped by
RPi distributions in favor of v4l2. (For GStreamer \< 1.22, a
backport of changes from the GStreamer development branch is needed:
this has now been done by Raspberry Pi OS (Bullseye); for other
distributions a
using Video4Linux2 (v4l2), which supports both 32- and 64-bit
systems: this is the replacement for 32-bit-only OpenMAX (omx), for
which support by RPi distributions is being discontinued. (Until
GStreamer 1.22 is released, a backport of changes from the GStreamer
development branch is needed: this has now been done by Raspberry Pi
OS (Bullseye); for other distributions a
[patch](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
to the GStreamer Video4Linux2 plugin, available in the [UxPlay
Wiki](https://github.com/FDH2/UxPlay/wiki), is required.) See
[success
reports](https://github.com/FDH2/UxPlay/wiki/UxPlay-on-Raspberry-Pi:-success-reports:).
- **New**: Support for running on Microsoft Windows (so far only
tested on current Windows 10 64 bit, using MinGW-64 compiler in
MSYS2 environment).
- **New**: Support for running on Microsoft Windows (builds with the
MinGW-64 compiler in the unix-like MSYS2 environment).
This project is a GPLv3 open source unix AirPlay2 Mirror server for
Linux, macOS, and \*BSD. It was initially developed by
@@ -59,18 +58,22 @@ UxPlay is tested on a number of systems, including (among others) Debian
20.3, Pop!\_OS 22.04 (NVIDIA edition), Rocky Linux 8.6 (a CentOS
successor), OpenSUSE 15.4, Arch Linux 5.16.8, macOS 12.3 (Intel and M1),
FreeBSD 13.1. On Raspberry Pi, it is tested on Raspberry Pi OS
(Bullseye) (32- and 64-bit), Ubuntu 22.04, and Manjaro RPi4 22.04.
(Bullseye) (32- and 64-bit), Ubuntu 22.04, and Manjaro RPi4 22.04. Also
tested on 64-bit Windows 10 and 11.
Its main use is to act like an AppleTV for screen-mirroring (with audio)
of iOS/iPadOS/macOS clients (iPhones, iPads, MacBooks) in a window on
the server display (with the possibility of sharing that window on
screen-sharing applications such as Zoom) on a host running Linux,
macOS, or other unix. UxPlay supports Apple's AirPlay2 protocol using
"Legacy Pairing", but some features are missing. (Details of what is
publically known about Apple's AirPlay 2 protocol can be found
of iOS/iPadOS/macOS clients (iPhone, iPod Touch, iPad, Mac computers) in
a window on the server display (with the possibility of sharing that
window on screen-sharing applications such as Zoom) on a host running
Linux, macOS, or other unix (and now also Microsoft Windows). UxPlay
supports Apple's AirPlay2 protocol using "Legacy Pairing", but some
features are missing. (Details of what is publically 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)).
and [here](https://emanuelecozzi.net/docs/airplay2)). While there is no
guarantee that future iOS releases will keep supporting "Legacy
Pairing", the recent iOS 16 release 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
@@ -88,15 +91,12 @@ 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 such as `feh`:
run "`uxplay -ca <name> &`" in the background, then run
"`feh -R 1 <name>`" in the foreground; terminate with
"`ctrl-C fg ctrl-C`". *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.*
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
@@ -109,7 +109,7 @@ connection; cover-art display stops/restarts as you leave/re-enter*
(where the client controls a web server on the AirPlay server that
directly receives content to avoid it being decoded and re-encoded
by the client), using the icon for AirPlay video in apps such as the
You Tube app will only send audio (in lossless ALAC format) without
YouTube app will only send audio (in lossless ALAC format) without
the accompanying video.**
### Possibility for using hardware-accelerated h264 video-decoding, if available.
@@ -290,6 +290,12 @@ prevents UxPlay from receiving client connection requests unless some
network ports are opened. See [Troubleshooting](#troubleshooting) below
for help with this or other problems.
To 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`".
**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
@@ -320,8 +326,9 @@ system without X11 (like R Pi OS Lite) with framebuffer video, use
`<videosink>` = `waylandsink`. For convenience, these options are also
available combined in options `-rpi`, `-rpigl` `-rpifb`, `-rpiwl`,
respectively provided for X11, X11 with OpenGL, framebuffer, and Wayland
systems. You may find the simple "uxplay", (which lets GStreamer try to
find the best video solution by itself) provides the best results.
systems. You may find that just "`uxplay`", (*without* `-v4l2` or
`-rpi*` options, which lets GStreamer try to find the best video
solution by itself) provides the best results.
- **For UxPlay-1.56 and later, if you are not using the latest
GStreamer patches from the Wiki, you will need to use the UxPlay
@@ -331,7 +338,7 @@ find the best video solution by itself) provides the best results.
have a fix for this, which is included in the latest patches, so
beginning with UxPlay-1.56, the bt709 fix is no longer automatically
applied. **After a recent update, Raspberry Pi OS (Bullseye) now
supplies an already-patched GStreamer-1.18.4 that can run UxPlay,
supplies an already-patched GStreamer-1.18.4 that works with UxPlay,
but needs the `-bt709` option with UxPlay-1.56 or later.**
- Tip: to start UxPlay on a remote host (such as a Raspberry Pi) using
@@ -469,7 +476,9 @@ from the initial "-s wxh" setting (also use the iPad/iPhone setting that
locks the screen orientation against switching between portrait and
landscape mode as the device is rotated).
## Building UxPlay on Windows (tested on Windows 10 64bit, using MSYS2 and MinGW-64 compiler)
## 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** from the
official Apple site
@@ -559,7 +568,9 @@ supports additional options such as
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.
"`device`" is not specified, the default audio device is used. The
executable uxplay.exe can also be run without the MSYS2 environment
(using the Windows Terminal, with `C:\msys64\mingw64\bin\uxplay`).
# Usage
@@ -692,12 +703,12 @@ 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
**-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). 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.
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.
**-nc** maintains previous UxPlay \< 1.45 behavior that does **not
close** the video window when the the client sends the "Stop Mirroring"
@@ -758,7 +769,10 @@ time a SPS/PPS NAL unit arrives. To change the name *videodump*, use
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*.
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
@@ -830,7 +844,9 @@ Wiki](https://github.com/FDH2/UxPlay/wiki).
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).
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 (-rpi option) only work with hardware GPU
decoding if the Video4Linux2 plugin in GStreamer v1.20.x or earlier has
@@ -975,8 +991,7 @@ other settings are set in `UxPlay/lib/dnssdint.h`.
# Changelog
1.56 2022-09-01 Added support for building and running UxPlay-1.56 on
Windows (github source only, no changes to Unix (Linux, \*BSD, macOS)
codebase.)
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.