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

README edits + cosmetic changes to manpage, -h output

Browse Source
This commit is contained in:
fduncanh
2022-08-20 17:44:53 -04:00
parent 26a9403397
commit d7648e8d73
5 changed files with 264 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
README.html
View File

@@ -12,9 +12,9 @@ href="https://github.com/FDH2/UxPlay">https://github.com/FDH2/UxPlay</a>
<li>GPLv3, open source.</li>
<li>Originally supported only AirPlay Mirror protocol, now has added
support for AirPlay Audio-only (Apple Lossless ALAC) streaming from
current iOS/iPadOS 15.5 clients. <strong>There is no support for
current iOS/iPadOS 15.6 clients. <strong>There is no support for
Airplay2 video-streaming protocol, and none is planned.</strong></li>
<li>macOS computers (2011 or later, both Intel and “Apple Silicon” M1
<li>macOS computers (2011 or later, both Intel and “Apple Silicon” M1/M2
systems) can act either as AirPlay clients, or as the server running
UxPlay. Using AirPlay, UxPlay can emulate a second display for macOS
clients.</li>
@@ -95,15 +95,18 @@ a</em> <strong>Mirror</strong> <em>mode connection; cover-art display
stops/restarts as you leave/re-enter</em> <strong>Audio</strong>
<em>mode.</em></p>
<ul>
<li><strong>Note that Apple video-DRM (as found in AppleTV.app content
on the client) cannot be decrypted by UxPlay, and (unlike a true
AppleTV), the UxPlay server does not allow the Apple client to run a
http connection on the server that directly streams content from the
internet to the server, instead of streaming it to the client, and then
re-streaming to the server. Unlike AppleTV.app, DRM-free apps like
youtube.app can be viewed and listened to in Mirror mode, but using the
youtube.app icon for AirPlay video will only send ALAC sound without the
accompanying video.</strong></li>
<li><p><strong>Note that Apple video-DRM (as found in “Apple TV app”
content on the client) cannot be decrypted by UxPlay, and the Apple TV
app cannot be watched using UxPlay’s AirPlay Mirror mode (only the
unprotected audio will be streamed, in AAC format), but both video and
audio content from DRM-free apps like “YouTube app” will be streamed by
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
accompanying video.</strong></p></li>
</ul>
<h3
id="possibility-for-using-hardware-accelerated-h264-video-decoding-if-available.">Possibility
@@ -151,42 +154,44 @@ instructions for GStreamer</a> in the <a
href="https://github.com/FDH2/UxPlay/wiki">UxPlay Wiki</a> for GStreamer
1.18.4 and later.</p></li>
</ul>
<h3
id="note-to-packagers-openssl-3.0.0-solves-gpl-v3-license-issues.">Note
to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.</h3>
<p>Some Linux distributions such as Debian do not allow distribution of
compiled GPL code linked to OpenSSL-1.1.1 because its license has some
incompatibilities with GPL code, unless all authors have given an
“exception” to allow such linking (the historical origins of UxPlay make
this impossible to obtain). Other distributions treat OpenSSL as a
“System Library” to which the GPL allows linking.</p>
<p>For “GPL-strict” distributions, UxPlay can be built using OpenSSL-
3.0.0, which has a new <a
href="https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/">GPLv3-compatible
license</a>.</p>
<h3 id="note-to-packagers">Note to packagers:</h3>
<p>UxPlay’s GPLv3 license does not have an added “exception” explicitly
allowing it to be distributed in compiled form when linked to OpenSSL
versions <strong>prior to v. 3.0.0</strong> (older versions of OpenSSL
have a license clause incompatible with the GPL unless OpenSSL can be
regarded as a “System Library”, which it is in *BSD). Many Linux
distributions treat OpenSSL as a “System Library”, but some
(e.g. Debian) do not: in this case, the issue is solved by linking with
OpenSSL-3.0.0 or later.</p>
<h1 id="getting-uxplay">Getting UxPlay:</h1>
<ul>
<li>Your distribution may already provide a pre-built uxplay package. It
will be included in the next Debian release “Bookworm” (currently in
“testing” phase) and Ubuntu-22.04 already provides a uxplay-1.46 package
based on this. Arch-based distributions also have AUR self-building
packages for both the latest UxPlay release and the current GitHub
version. To build the latest version yourself, follow the instructions
below.</li>
</ul>
<p>Either download and unzip <a
href="https://github.com/FDH2/UxPlay/archive/refs/heads/master.zip">UxPlay-master.zip</a>,
or (if git is installed): “git clone https://github.com/FDH2/UxPlay”.
You can also download a recent or earlier version listed in <a
href="https://github.com/FDH2/UxPlay/releases">Releases</a>.</p>
<ul>
<li>Current UxPlay is also a pull request on the original site
https://github.com/antimof/UxPlay ; that original project is inactive,
but the pull requests are now being periodically merged with the antimof
tree (thank you antimof!).</li>
<li>A recent UxPlay can also be found on the original <a
href="https://github.com/antimof/UxPlay">antimof site</a>; that original
project is inactive, but is usually kept current or almost-current with
the <a href="https://github.com/FDH2/UxPlay">active UxPlay github
site</a> (thank you antimof!).</li>
</ul>
<h2 id="building-uxplay-on-linux-or-bsd">Building UxPlay on Linux (or
*BSD):</h2>
<h3 id="debian-based-systems">Debian-based systems:</h3>
<ul>
<li>Note that the current Debian “testing” distribution (for eventual
release as Debian 12/Bookworm) now includes uxplay, so future
Debian-based distributions may offer a pre-built uxplay package.</li>
</ul>
<p>(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for
macOS, see below). See <a href="#troubleshooting">Troubleshooting</a>
below for help with any difficulties.</p>
<p>(Adapt these instructions for non-Debian-based Linuxes or *BSD; for
macOS, see specific instruction below). See <a
href="#troubleshooting">Troubleshooting</a> below for help with any
difficulties.</p>
<p>You need a C/C++ compiler (e.g. g++) with the standard development
libraries installed. Debian-based systems provide a package
“build-essential” for use in compiling software. You also need
@@ -212,48 +217,57 @@ follow the instructions below:</p>
optimization for the computer it is built on; when this is not the case,
as when you are packaging for a distribution, use the cmake option
<code>-DNO_MARCH_NATIVE=ON</code>.</p>
<p>If you use Gstreamer older than 1.20, and wish to share the UxPlay
screen using screen-sharing apps such as Zoom, you should use the cmake
option “<code>-DZOOMFIX=ON</code>” in step 3. This requires the X11
development libraries to be installed: on Debian-based systems do this
with “<code>sudo apt-get install libx11-dev</code>” . “ZOOMFIX” is not
needed on macOS, or if you are using non-X11 windows (such as OpenGL) on
Linux. See <a href="#zoomfix-compile-time-option">ZOOMFIX compile-time
option</a> below for more information, and alternatives to “ZOOMFIX”</p>
<ol type="1">
<li><code>sudo apt-get install libssl-dev libplist-dev</code> (unless
<li><code>sudo apt-get install libssl-dev libplist-dev</code>“. (unless
you need to build OpenSSL and libplist from source).</li>
<li><code>sudo apt-get install libavahi-compat-libdnssd-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev</code>.</li>
<li><code>sudo apt-get install libx11-dev</code> (only needed if you
invoke the “ZOOMFIX” X11 display-name fix in the next step)</li>
<li><code>cmake .</code> (or “<code>cmake -DZOOMFIX=ON .</code>” to get
a screen-sharing fix to make X11 mirror display windows visible to
screen-sharing applications such as Zoom, see <a
href="#zoomfix-compile-time-option">ZOOMFIX compile-time option</a>
below). <strong>ZOOMFIX is only needed for GStreamer-1.18.x or
earlier</strong>.</li>
<li><code>cmake .</code> (For a cleaner build, which is useful if you
modify the source, replace this by
“<code>mkdir build; cd build; cmake ..</code>”: you can then delete the
<code>build</code> directory if needed, without affecting the source.)
Also add any cmake “<code>-D</code>” options here as needed (e.g,
ZOOMFIX=ON or NO_MARCH_NATIVE=ON).</li>
<li><code>make</code></li>
<li><code>sudo make install</code> (you can afterwards uninstall with
<code>sudo make uninstall</code> in the same directory in which this was
run).</li>
<li>Install GStreamer plugins that you need:
<code>sudo apt-get install gstreamer1.0-&lt;plugin&gt;</code>; values of
<code>&lt;plugin&gt;</code> needed are: “<strong>plugins-base</strong>”,
“<strong>libav</strong>” (for sound), “<strong>plugins-good</strong>”
(for v4l2 hardware h264 decoding) and “<strong>plugins-bad</strong>”
(for h264 decoding). Also needed may be “<strong>gl</strong>” for OpenGL
support (which may be useful, and should be used with h264 decoding by
the NVIDIA GPU), and “<strong>x</strong>” for X11 support, although
these may already be installed; “<strong>vaapi</strong>” is needed for
hardware-accelerated h264 video decoding by Intel or AMD graphics (but
not for use with NVIDIA using proprietary drivers). Also install
“<strong>tools</strong>” to get the utility gst-inspect-1.0 for
examining the GStreamer installation.</li>
</ol>
<p><em>If you intend to modify the code, use a separate “build”
directory: replace</em> “<code>cmake [ ] .</code>” <em>by</em>
“<code>mkdir build ; cd build ; cmake [ ] ..</code>”; <em>you can then
clean the build directory with</em> “<code>rm -rf build/*</code>”
<em>(run from within the UxPlay source directory) without affecting the
source directories which contain your modifications</em>.</p>
<p>The above script installs the executable file “<code>uxplay</code>”
to <code>/usr/local/bin</code>, (and installs a manpage to somewhere
like <code>/usr/local/share/man/man1</code> and README files to
somewhere like <code>/usr/local/share/doc/uxplay</code>). The uxplay
executable can also be found in the build directory after the build
processs, if you wish to test before installing.</p>
process, if you wish to test before installing (in which case the
GStreamer plugins must already be installed)</p>
<p>Next install the GStreamer plugins that are needed with
<code>sudo apt-get install gstreamer1.0-&lt;plugin&gt;</code>. Values of
<code>&lt;plugin&gt;</code> required are:</p>
<ol type="1">
<li>“<strong>plugins-base</strong>”</li>
<li>“<strong>libav</strong>” (for sound),</li>
<li>“<strong>plugins-good</strong>” (for v4l2 hardware h264
decoding)</li>
<li>“<strong>plugins-bad</strong>” (for h264 decoding).</li>
</ol>
<p>Plugins that may also be needed include “<strong>gl</strong>” for
OpenGL support (which may be useful, and should be used with h264
decoding by the NVIDIA GPU), and “<strong>x</strong>” for X11 support,
although these may already be installed; “<strong>vaapi</strong>” is
needed for hardware-accelerated h264 video decoding by Intel or AMD
graphics (but not for use with NVIDIA using proprietary drivers). Also
install “<strong>tools</strong>” to get the utility gst-inspect-1.0 for
examining the GStreamer installation. If sound is not working,
“<strong>alsa</strong>”“,”<strong>pulseaudio</strong>”, or
“<strong>pipewire</strong>” plugins may need to be installed, depending
on how your audio is set up.</p>
<p><strong>Finally, run uxplay in a terminal window</strong>. Use Ctrl-C
(or close the window) to terminate it when done. If it is not seen by
the iOS client’s drop-down “Screen Mirroring” panel, check that your
@@ -347,8 +361,7 @@ gstreamer1-libav, gstreamer1-plugins, gstreamer1-plugins-* (* = core,
good, bad, x, gtk, gl, vulkan, pulse …), (+ gstreamer1-vaapi for Intel
graphics). Either avahi-libdns or mDNSResponder must also be installed
to provide the dns_sd library. OpenSSL is already installed as a System
Library. “ZOOMFIX” is untested; don’t try to use it on FreeBSD unless
you need it.</p></li>
Library.</p></li>
</ul>
<h2
id="building-uxplay-on-macos-intel-x86_64-and-apple-silicon-m1-macs">Building
@@ -358,7 +371,7 @@ Macs)</strong></h2>
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.</em></p>
<p>These instructions for macOS asssume that the Xcode command-line
<p>These instructions for macOS assume that the Xcode command-line
developer tools are installed (if Xcode is installed, open the Terminal,
type “sudo xcode-select –install” and accept the conditions).</p>
<p>It is also assumed that CMake &gt;= 3.13 is installed: this can be
@@ -383,9 +396,9 @@ it, but compiled to use X11).</li>
</ul>
<p><strong>For the “official” release</strong>: install both the macOS
runtime and development installer packages. Assuming that the latest
release is 1.20.2. install
<code>gstreamer-1.0-1.20.2-universal.pkg</code> and
<code>gstreamer-1.0-devel-1.20.2-universal.pkg</code>. (If you have an
release is 1.20.3. install
<code>gstreamer-1.0-1.20.3-universal.pkg</code> and
<code>gstreamer-1.0-devel-1.20.3-universal.pkg</code>. (If you have an
Intel-architecture Mac, and have problems with the “universal” packages,
you can also use <code>gstreamer-1.0-1.18.6-x86_64.pkg</code> and
<code>gstreamer-1.0-devel-1.18.6-x86_64.pkg</code>.) Click on them to
@@ -533,10 +546,10 @@ Raspberry Pi “Desktop” systems using the Wayland video compositor (use
for Ubuntu 21.10 for Raspberry Pi 4B).</p>
<p><strong>-as <em>audiosink</em></strong> chooses the GStreamer
audiosink, instead of letting autoaudiosink pick it for you. Some
audiosink choices are: pulsesink, alsasink, osssink, oss4sink, and
osxaudiosink (for macOS). Using quotes “…” might allow some parameters
to be included with the audiosink name. (Some choices of audiosink might
not work on your system.)</p>
audiosink choices are: pulsesink, alsasink, pipewiresink, osssink,
oss4sink, jackaudiosink, a2dpsink, and osxaudiosink (for macOS). Using
quotes “…” might allow some parameters to be included with the audiosink
name. (Some choices of audiosink might not work on your system.)</p>
<p><strong>-as 0</strong> (or just <strong>-a</strong>) suppresses
playing of streamed audio, but displays streamed video.</p>
<p><strong>-ca <em>filename</em></strong> provides a file (where
@@ -808,15 +821,13 @@ uxplay.</p>
sourceVersion 220.68; this can also be changed in global.h. It had been
thought that it was necessary for UxPlay to claim to be an older 32 bit
AppleTV model that cannot run modern 64bit tvOS, in order for the client
to use a “legacy” protocol for pairing with the server (see the
<em>“Notes on AirPlay protocol versions”</em> at the end of this
README). However, UxPlay still 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); it seems that the use of “legacy”
protocol just requires bit 27 (listed as “SupportsLegacyPairing”) of the
“features” plist code (reported to 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>
to use a “legacy” protocol for pairing with the server. However, UxPlay
still 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);
it seems that the use of “legacy” protocol just requires bit 27 (listed
as “SupportsLegacyPairing”) of the “features” plist code (reported to
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-07-30 Remove -bt709 from -rpi, -rpiwl, -rpifb as GStreamer
is now fixed.</p>

133
README.md
View File

@@ -8,8 +8,8 @@ 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.5 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
from current iOS/iPadOS 15.6 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.
@@ -81,13 +81,15 @@ possible: in_ **Mirror** _mode, stop mirroring (or close the mirror window) and
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 AppleTV.app content on the client) cannot be decrypted by UxPlay,
and (unlike a true AppleTV), the UxPlay server does not allow the Apple
client to run a http connection on the server that directly streams
content from the internet to the server, instead of
streaming it to the client, and then re-streaming to the server. Unlike AppleTV.app, DRM-free apps like youtube.app
can be viewed and listened to in Mirror mode, but using the youtube.app icon for AirPlay video will only send
ALAC sound without the accompanying video.**
(as found in "Apple TV app" content on the client) cannot be decrypted by UxPlay, and
the Apple TV app cannot be watched using UxPlay's AirPlay Mirror mode (only the unprotected audio will be streamed, in AAC format),
but both video and audio content from DRM-free apps like "YouTube app" will be streamed by UxPlay in Mirror mode.**
* **As UxPlay does not 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 accompanying video.**
### Possibility for using hardware-accelerated h264 video-decoding, if available.
@@ -132,39 +134,36 @@ if not, software decoding is used.
[patching instructions for GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
in the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki) for GStreamer 1.18.4 and later.
### Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.
Some Linux distributions such as Debian do not allow distribution of compiled
GPL code linked to OpenSSL-1.1.1 because its license
has some incompatibilities with GPL code, unless all authors have
given an "exception" to allow such linking (the historical origins of UxPlay
make this impossible to obtain). Other distributions
treat OpenSSL as a "System Library" to which the GPL allows linking.
### Note to packagers:
For "GPL-strict" distributions, UxPlay can be built using OpenSSL- 3.0.0,
which has a new [GPLv3-compatible license](https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/).
UxPlay's GPLv3 license does not have an added
"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:
* Your distribution may already provide a pre-built uxplay package. It will be included in the next Debian release "Bookworm"
(currently in "testing" phase) and Ubuntu-22.04 already provides a uxplay-1.46 package based on this. Arch-based distributions also
have AUR self-building packages for both the latest UxPlay release and the current GitHub version.
To build the latest version yourself, follow the instructions below.
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).
* Current UxPlay is also a pull request on the
original site https://github.com/antimof/UxPlay ; that original
project is inactive, but the pull requests are
now being periodically merged with the antimof tree (thank you antimof!).
* 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:
* Note that the current Debian "testing" distribution
(for eventual release as Debian 12/Bookworm) now includes uxplay, so
future Debian-based distributions may offer a pre-built uxplay package.
(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for macOS,
see below). See [Troubleshooting](#troubleshooting) below for help with
(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
@@ -190,40 +189,47 @@ zipfile downloads, "UxPlay" for "git clone" downloads), then follow the instruct
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`.
1. `sudo apt-get install libssl-dev libplist-dev`
(unless you need to build OpenSSL and libplist from source).
2. `sudo apt-get install libavahi-compat-libdnssd-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev`.
3. `sudo apt-get install libx11-dev` (only needed if you invoke
the "ZOOMFIX" X11 display-name fix in the next step)
4. `cmake .` (or "`cmake -DZOOMFIX=ON .`" to get a screen-sharing fix to
make X11 mirror display windows visible to screen-sharing applications
such as Zoom, see [ZOOMFIX compile-time option](#zoomfix-compile-time-option) below).
**ZOOMFIX is only needed for GStreamer-1.18.x or earlier**.
5. `make`
6. `sudo make install` (you can afterwards uninstall with ``sudo make uninstall``
in the same directory in which this was run).
7. Install GStreamer plugins that you need: `sudo apt-get install gstreamer1.0-<plugin>`;
values of `<plugin>` needed are: "**plugins-base**", "**libav**" (for sound),
"**plugins-good**" (for v4l2 hardware h264 decoding)
and "**plugins-bad**" (for h264 decoding). Also needed may
be "**gl**" for OpenGL support (which may be useful, and should
be used with h264 decoding by the NVIDIA GPU), 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).
Also install "**tools**" to get the utility gst-inspect-1.0 for
examining the GStreamer installation.
If you use Gstreamer older than 1.20, and wish to share the UxPlay screen using screen-sharing apps such
as Zoom, you should use the cmake option "` -DZOOMFIX=ON`" in step 3. This requires
the X11 development libraries to be installed: on Debian-based systems do this with "`sudo apt-get install libx11-dev`" .
"ZOOMFIX" is not needed on macOS, or if you are using non-X11 windows
(such as OpenGL) on Linux. See [ZOOMFIX compile-time option](#zoomfix-compile-time-option) below for more information,
and alternatives to "ZOOMFIX"
_If you intend to modify the code, use a separate "build" directory:
replace_ "`cmake [ ] .`" _by_ "``mkdir build ; cd build ; cmake [ ] ..``"; _you can then clean
the build directory with_ "`rm -rf build/* `" _(run from within the UxPlay source directory) without affecting
the source directories which contain your modifications_.
1. `sudo apt-get install libssl-dev libplist-dev`".
(unless you need to build OpenSSL and libplist from source).
2. `sudo apt-get install libavahi-compat-libdnssd-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev`.
3. `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
`build` directory if needed, without affecting the source.) Also add any cmake "`-D`" options
here as needed (e.g, ZOOMFIX=ON or NO_MARCH_NATIVE=ON).
4. `make`
5. `sudo make install` (you can afterwards uninstall with ``sudo make uninstall``
in the same directory in which this was run).
The above script installs the executable file "`uxplay`" to `/usr/local/bin`, (and installs a manpage to
somewhere like `/usr/local/share/man/man1` and README
files to somewhere like `/usr/local/share/doc/uxplay`).
The uxplay executable can also be found in the build directory after the build
processs, if you wish to test before installing.
process, if you wish to test before installing (in which case
the GStreamer plugins must already be installed)
Next install the GStreamer plugins that are needed with `sudo apt-get 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).
Plugins that may also be needed include "**gl**" for OpenGL support (which may be useful, and should
be used with h264 decoding by the NVIDIA GPU), 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).
Also install "**tools**" to get the utility gst-inspect-1.0 for
examining the GStreamer installation. If sound is not working, "**alsa**"", "**pulseaudio**",
or "**pipewire**" plugins may need to be installed, depending on how your audio is set up.
**Finally, run uxplay in a terminal window**. Use Ctrl-C (or close the window) to terminate it when done. If it is not seen by the
iOS client's drop-down "Screen Mirroring" panel, check that your DNS-SD
@@ -299,7 +305,7 @@ for Intel graphics). (**Also available as a package in AUR**).
* **FreeBSD:** (sudo pkg install) libplist gstreamer1, gstreamer1-libav, gstreamer1-plugins, gstreamer1-plugins-*
(\* = core, good, bad, x, gtk, gl, vulkan, pulse ...), (+ gstreamer1-vaapi for Intel graphics).
Either avahi-libdns or mDNSResponder must also be installed to provide the dns_sd library.
OpenSSL is already installed as a System Library. "ZOOMFIX" is untested; don't try to use it on FreeBSD unless you need it.
OpenSSL is already installed as a System Library.
## Building UxPlay on macOS: **(Intel X86_64 and "Apple Silicon" M1 Macs)**
@@ -307,7 +313,7 @@ OpenSSL is already installed as a System Library. "ZOOMFIX" is untested; don't
_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 asssume that the Xcode command-line developer tools are installed (if Xcode is
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:
@@ -326,8 +332,8 @@ Next get the latest macOS release of GStreamer-1.0.
from [https://gstreamer.freedesktop.org/download/](https://gstreamer.freedesktop.org/download/). The alternative is to install it from Homebrew
(MacPorts also supplies it, but compiled to use X11).
**For the "official" release**: install both the macOS runtime and development installer packages. Assuming that the latest release is 1.20.2.
install `gstreamer-1.0-1.20.2-universal.pkg` and ``gstreamer-1.0-devel-1.20.2-universal.pkg``. (If
**For the "official" release**: install both the macOS runtime and development installer packages. Assuming that the latest release is 1.20.3.
install `gstreamer-1.0-1.20.3-universal.pkg` and ``gstreamer-1.0-devel-1.20.3-universal.pkg``. (If
you have an Intel-architecture Mac, and have problems with the "universal" packages, you can also
use `gstreamer-1.0-1.18.6-x86_64.pkg` and ``gstreamer-1.0-devel-1.18.6-x86_64.pkg``.) Click on them to
install (they install to /Library/FrameWorks/GStreamer.framework).
@@ -465,8 +471,8 @@ which will not work if a firewall is running.
Ubuntu 21.10 for Raspberry Pi 4B).
**-as _audiosink_** chooses the GStreamer audiosink, instead of letting
autoaudiosink pick it for you. Some audiosink choices are: pulsesink, alsasink,
osssink, oss4sink, and osxaudiosink (for macOS). Using quotes
autoaudiosink pick it for you. Some audiosink choices are: pulsesink, alsasink, pipewiresink,
osssink, oss4sink, jackaudiosink, a2dpsink, and osxaudiosink (for macOS). Using quotes
"..." might allow some parameters to be included with the audiosink name.
(Some choices of audiosink might not work on your system.)
@@ -687,8 +693,7 @@ Note that Uxplay declares itself to be an AppleTV3,2 with a
sourceVersion 220.68; this can also be changed in global.h. It had been thought
that it was necessary for UxPlay to claim to be an older 32 bit
AppleTV model that cannot run modern 64bit tvOS, in order for the client
to use a "legacy" protocol for pairing with the server (see
the _"Notes on AirPlay protocol versions"_ at the end of this README).
to use a "legacy" protocol for pairing with the server.
However, UxPlay still 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); it seems that the use of "legacy" protocol just requires bit 27 (listed as

174
README.txt
View File

@@ -7,9 +7,9 @@ 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.5 clients. **There is no support for Airplay2
current iOS/iPadOS 15.6 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
- 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.
@@ -86,15 +86,19 @@ stop mirroring (or close the mirror window) and start an* **Audio**
connection; cover-art display stops/restarts as you leave/re-enter*
**Audio** *mode.*
- **Note that Apple video-DRM (as found in AppleTV.app content on the
client) cannot be decrypted by UxPlay, and (unlike a true AppleTV),
the UxPlay server does not allow the Apple client to run a http
connection on the server that directly streams content from the
internet to the server, instead of streaming it to the client, and
then re-streaming to the server. Unlike AppleTV.app, DRM-free apps
like youtube.app can be viewed and listened to in Mirror mode, but
using the youtube.app icon for AirPlay video will only send ALAC
sound without the accompanying video.**
- **Note that Apple video-DRM (as found in "Apple TV app" content on
the client) cannot be decrypted by UxPlay, and the Apple TV app
cannot be watched using UxPlay's AirPlay Mirror mode (only the
unprotected audio will be streamed, in AAC format), but both video
and audio content from DRM-free apps like "YouTube app" will be
streamed by UxPlay in Mirror mode.**
- **As UxPlay does not 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 accompanying video.**
### Possibility for using hardware-accelerated h264 video-decoding, if available.
@@ -143,43 +147,46 @@ used.
in the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki) for
GStreamer 1.18.4 and later.
### Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.
### Note to packagers:
Some Linux distributions such as Debian do not allow distribution of
compiled GPL code linked to OpenSSL-1.1.1 because its license has some
incompatibilities with GPL code, unless all authors have given an
"exception" to allow such linking (the historical origins of UxPlay make
this impossible to obtain). Other distributions treat OpenSSL as a
"System Library" to which the GPL allows linking.
For "GPL-strict" distributions, UxPlay can be built using OpenSSL-
3.0.0, which has a new [GPLv3-compatible
license](https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/).
UxPlay's GPLv3 license does not have an added "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:
- Your distribution may already provide a pre-built uxplay package. It
will be included in the next Debian release "Bookworm" (currently in
"testing" phase) and Ubuntu-22.04 already provides a uxplay-1.46
package based on this. Arch-based distributions also have AUR
self-building packages for both the latest UxPlay release and the
current GitHub version. To build the latest version yourself, follow
the instructions below.
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).
- Current UxPlay is also a pull request on the original site
https://github.com/antimof/UxPlay ; that original project is
inactive, but the pull requests are now being periodically merged
with the antimof tree (thank you antimof!).
- 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:
- Note that the current Debian "testing" distribution (for eventual
release as Debian 12/Bookworm) now includes uxplay, so future
Debian-based distributions may offer a pre-built uxplay package.
(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for
macOS, see below). See [Troubleshooting](#troubleshooting) below for
help with any difficulties.
(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
@@ -208,45 +215,53 @@ 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`.
1. `sudo apt-get install libssl-dev libplist-dev` (unless you need to
If you use Gstreamer older than 1.20, and wish to share the UxPlay
screen using screen-sharing apps such as Zoom, you should use the cmake
option "`-DZOOMFIX=ON`" in step 3. This requires the X11 development
libraries to be installed: on Debian-based systems do this with
"`sudo apt-get install libx11-dev`" . "ZOOMFIX" is not needed on macOS,
or if you are using non-X11 windows (such as OpenGL) on Linux. See
[ZOOMFIX compile-time option](#zoomfix-compile-time-option) below for
more information, and alternatives to "ZOOMFIX"
1. `sudo apt-get install libssl-dev libplist-dev`". (unless you need to
build OpenSSL and libplist from source).
2. `sudo apt-get install libavahi-compat-libdnssd-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev`.
3. `sudo apt-get install libx11-dev` (only needed if you invoke the
"ZOOMFIX" X11 display-name fix in the next step)
4. `cmake .` (or "`cmake -DZOOMFIX=ON .`" to get a screen-sharing fix
to make X11 mirror display windows visible to screen-sharing
applications such as Zoom, see [ZOOMFIX compile-time
option](#zoomfix-compile-time-option) below). **ZOOMFIX is only
needed for GStreamer-1.18.x or earlier**.
5. `make`
6. `sudo make install` (you can afterwards uninstall with
3. `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 `build` directory if needed, without affecting the
source.) Also add any cmake "`-D`" options here as needed (e.g,
ZOOMFIX=ON or NO_MARCH_NATIVE=ON).
4. `make`
5. `sudo make install` (you can afterwards uninstall with
`sudo make uninstall` in the same directory in which this was run).
7. Install GStreamer plugins that you need:
`sudo apt-get install gstreamer1.0-<plugin>`; values of `<plugin>`
needed are: "**plugins-base**", "**libav**" (for sound),
"**plugins-good**" (for v4l2 hardware h264 decoding) and
"**plugins-bad**" (for h264 decoding). Also needed may be "**gl**"
for OpenGL support (which may be useful, and should be used with
h264 decoding by the NVIDIA GPU), 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). Also
install "**tools**" to get the utility gst-inspect-1.0 for examining
the GStreamer installation.
*If you intend to modify the code, use a separate "build" directory:
replace* "`cmake [ ] .`" *by*
"`mkdir build ; cd build ; cmake [ ] ..`"; *you can then clean the build
directory with* "`rm -rf build/*`" *(run from within the UxPlay source
directory) without affecting the source directories which contain your
modifications*.
The above script installs the executable file "`uxplay`" to
`/usr/local/bin`, (and installs a manpage to somewhere like
`/usr/local/share/man/man1` and README files to somewhere like
`/usr/local/share/doc/uxplay`). The uxplay executable can also be found
in the build directory after the build processs, if you wish to test
before installing.
in the build directory after the build process, if you wish to test
before installing (in which case the GStreamer plugins must already be
installed)
Next install the GStreamer plugins that are needed with
`sudo apt-get 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).
Plugins that may also be needed include "**gl**" for OpenGL support
(which may be useful, and should be used with h264 decoding by the
NVIDIA GPU), 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). Also install "**tools**" to get the utility
gst-inspect-1.0 for examining the GStreamer installation. If sound is
not working, "**alsa**"","**pulseaudio**", or "**pipewire**" plugins may
need to be installed, depending on how your audio is set up.
**Finally, run uxplay in a terminal window**. Use Ctrl-C (or close the
window) to terminate it when done. If it is not seen by the iOS client's
@@ -344,8 +359,7 @@ Terminal output is saved to FILE (which can be /dev/null to discard it).
core, good, bad, x, gtk, gl, vulkan, pulse ...), (+ gstreamer1-vaapi
for Intel graphics). Either avahi-libdns or mDNSResponder must also
be installed to provide the dns_sd library. OpenSSL is already
installed as a System Library. "ZOOMFIX" is untested; don't try to
use it on FreeBSD unless you need it.
installed as a System Library.
## Building UxPlay on macOS: **(Intel X86_64 and "Apple Silicon" M1 Macs)**
@@ -354,7 +368,7 @@ 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 asssume that the Xcode command-line
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).
@@ -379,8 +393,8 @@ Next get the latest macOS release of GStreamer-1.0.
**For the "official" release**: install both the macOS runtime and
development installer packages. Assuming that the latest release is
1.20.2. install `gstreamer-1.0-1.20.2-universal.pkg` and
`gstreamer-1.0-devel-1.20.2-universal.pkg`. (If you have an
1.20.3. install `gstreamer-1.0-1.20.3-universal.pkg` and
`gstreamer-1.0-devel-1.20.3-universal.pkg`. (If you have an
Intel-architecture Mac, and have problems with the "universal" packages,
you can also use `gstreamer-1.0-1.18.6-x86_64.pkg` and
`gstreamer-1.0-devel-1.18.6-x86_64.pkg`.) Click on them to install (they
@@ -546,9 +560,10 @@ systems using the framebuffer, like RPi OS Bullseye Lite).
**-as *audiosink*** chooses the GStreamer audiosink, instead of letting
autoaudiosink pick it for you. Some audiosink choices are: pulsesink,
alsasink, osssink, oss4sink, and osxaudiosink (for macOS). Using quotes
"..." might allow some parameters to be included with the audiosink
name. (Some choices of audiosink might not work on your system.)
alsasink, pipewiresink, osssink, oss4sink, jackaudiosink, a2dpsink, and
osxaudiosink (for macOS). Using quotes "..." might allow some parameters
to be included with the audiosink name. (Some choices of audiosink might
not work on your system.)
**-as 0** (or just **-a**) suppresses playing of streamed audio, but
displays streamed video.
@@ -838,14 +853,13 @@ Note that Uxplay declares itself to be an AppleTV3,2 with a
sourceVersion 220.68; this can also be changed in global.h. It had been
thought that it was necessary for UxPlay to claim to be an older 32 bit
AppleTV model that cannot run modern 64bit tvOS, in order for the client
to use a "legacy" protocol for pairing with the server (see the *"Notes
on AirPlay protocol versions"* at the end of this README). However,
UxPlay still 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); it seems that the use of "legacy" protocol just requires
bit 27 (listed as "SupportsLegacyPairing") of the "features" plist code
(reported to the client by the AirPlay server) to be set. The "features"
code and other settings are set in `UxPlay/lib/dnssdint.h`.
to use a "legacy" protocol for pairing with the server. However, UxPlay
still 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);
it seems that the use of "legacy" protocol just requires bit 27 (listed
as "SupportsLegacyPairing") of the "features" plist code (reported to
the client by the AirPlay server) to be set. The "features" code and
other settings are set in `UxPlay/lib/dnssdint.h`.
# ChangeLog

6
uxplay.1
View File

@@ -58,7 +58,7 @@ UxPlay 1.56: An open\-source AirPlay mirroring server based on RPiPlay
.TP
\fB\-rpi\fR Same as "-v4l2" (for RPi=Rasberry Pi).
.TP
\fB\-rpigl\fR Same as "-v4l2 -vs glimagesink" for RPi.
\fB\-rpigl\fR Same as "-rpi -vs glimagesink" for RPi.
.TP
\fB\-rpifb\fR Same as "-rpi -vs kmssink" for RPi using framebuffer.
.TP
@@ -66,7 +66,9 @@ UxPlay 1.56: An open\-source AirPlay mirroring server based on RPiPlay
.TP
\fB\-as\fI sink\fR Choose the GStreamer audiosink; default "autoaudiosink"
.IP
choices:pulsesink,alsasink,osssink,oss4sink,osxaudiosink,..
choices:pulsesink,alsasink,pipewiresink,osssink,oss4sink,
.IP
jackaudiosink,a2dpsink,osxaudiosink,..
.PP
.TP
\fB\-as\fR 0 (or \fB\-a\fR) Turn audio off, streamed video only.

3
uxplay.cpp
View File

@@ -349,7 +349,8 @@ static void print_info (char *name) {
printf("-rpifb Same as \"-rpi -vs kmssink\" for RPi using framebuffer.\n");
printf("-rpiwl Same as \"-rpi -vs waylandsink\" for RPi using Wayland.\n");
printf("-as ... Choose the GStreamer audiosink; default \"autoaudiosink\"\n");
printf(" choices: pulsesink,alsasink,osssink,oss4sink,osxaudiosink\n");
printf(" choices include: pulsesink,alsasink,pipewiresink,osssink,\n");
printf(" oss4sink,jackaudiosink,a2dpsink,osxaudiosink, etc.\n");
printf("-as 0 (or -a) Turn audio off, streamed video only\n");
printf("-ca <fn> In Airplay Audio (ALAC) mode, write cover-art to file <fn>\n");
printf("-reset n Reset after 3n seconds client silence (default %d, 0=never)\n", NTP_TIMEOUT_LIMIT);