morgan/UxPlay
1
0
Fork 0
mirror of https://github.com/morgan9e/UxPlay synced 2026-04-15 00:34:05 +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

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