From 3b51197271b06c5e90829af609c58b53f88de3de Mon Sep 17 00:00:00 2001 From: fduncanh Date: Sat, 27 Nov 2021 12:57:25 -0500 Subject: [PATCH] README updates --- README.html | 10 ++++++---- README.md | 15 +++++++++++---- README.txt | 25 ++++++++++++++++++++----- 3 files changed, 37 insertions(+), 13 deletions(-) diff --git a/README.html b/README.html index c8933f17..728fab78 100644 --- a/README.html +++ b/README.html @@ -1,7 +1,7 @@

UxPlay 1.42: AirPlay/AirPlay-Mirror server for Linux, macOS, and Unix.

This project is a GPLv3 unix AirPlay server which now also works on macOS. Its main use is to act like an AppleTV for screen-mirroring (with audio) of iOS/macOS clients (iPads, iPhones, 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, using Apple’s AirPlay Mirror protocol first available in iOS 5. As well as screen mirroring, when not mirroring the screen it can also play Apple Lossless (ALAC) audio streamed from the client using the audio-only Airplay protocol. (Details of what is known about the AirPlay2 protocol can be found here and here).

The UxPlay server and its client must be on the same local area network, on which a Bonjour/Zeroconf mDNS/DNS-SD server is also running (only DNS-SD “Service Discovery” service is necessary, it is not necessary that the local network also be of the “.local” mDNS-based type). On Linux and BSD Unix servers, this is usually provided by Avahi, through the avahi-daemon service, and is included in most Linux distributions (this service can also be provided by macOS, iOS or Windows servers).

-

New: UxPlay > 1.38 now also supports the Airplay audio-only protocol as well as AirPlay Mirror protocol, and (when the client screen is not being mirrored) can play Apple Lossless (ALAC) 44100/16/2 audio streamed from the client in 2-channel stereo without video (the accompanying cover-art and metadata is received by the server, but not displayed). The initial connection to the client can be in AirPlay audio mode, or an initial Airplay Mirror connection can be switched to Airplay audio by selecting “Stop Mirroring” in the Screen Mirroring setting (or closing the mirror window) and reconnecting in audio-only AirPlay mode (this changes back to 44100/2 “Advanced Audio Coding” (AAC-ELD) compressed (lossy) audio if screen mirroring is (re)started).

+

New: UxPlay > 1.38 now also supports the Airplay audio-only protocol as well as AirPlay Mirror protocol, and (when the client screen is not being mirrored) can play Apple Lossless (ALAC) 44100/16/2 audio streamed from the client in 2-channel stereo without video (the accompanying cover-art and metadata is received by the server, but not displayed). The initial connection to the client can be in AirPlay audio mode, or an initial Airplay Mirror connection can be switched to Airplay audio by selecting “Stop Mirroring” in the Screen Mirroring setting (or closing the mirror window) and reconnecting in audio-only AirPlay mode (the audio stream changes back to “Advanced Audio Coding” (AAC-ELD) compressed (lossy) format if screen mirroring is (re)started).

UxPlay is based on https://github.com/FD-/RPiPlay, with GStreamer integration from https://github.com/antimof/UxPlay. (UxPlay only uses GStreamer, and does not contain the alternative Raspberry-Pi-specific audio and video renderers also found in RPiPlay.) Tested on Ubuntu 20.04, Linux Mint 20.2, OpenSUSE 15.3, macOS 10.15, FreeBSD 13.0.

Features: 1. Based on Gstreamer. 2. Video and audio are supported out of the box. 3. Gstreamer decoding is plugin agnostic. Uses accelerated decoders if available. For Intel graphics, VAAPI is preferable, (but don’t use VAAPI with nVidia). 4. Automatic screen orientation.

Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.

@@ -44,7 +44,7 @@

Building this version (macOS):

Other ways (Homebrew, MacPorts) to install GStreamer on macOS (not recommended):

First make sure that pkgconfig is installed (Homebrew: “brew install pkgconfig” ; MacPorts: “sudo port install pkgconfig” ).

    -

  1. with Homebrew: “brew install gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav”. This appears to be functionally equivalent to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies.

    2. +

  2. with Homebrew: “brew install gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav”. This appears to be functionally equivalent to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies. (However, as of November 2021, Homebrew offers a build of GStreamer for Apple Silicon, which then was not yet available on the offical GStreamer site.)

  3. with MacPorts: “sudo port install gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad gstreamer1-gst-libav”. The MacPorts GStreamer is built to use X11, so must be run from an XQuartz terminal, can use ZOOMFIX, and needs option “-vs ximagesink”. On an older unibody MacBook Pro, the default resolution wxh = 1920x1080 was too large for the non-retina display, but using option “-s 800x600” worked; However, the GStreamer pipeline is fragile against attempts to change the X11 window size, or to rotations that switch a connected client between portrait and landscape mode while uxplay is running. Using the MacPorts X11 GStreamer is only viable if the image size is left unchanged 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).

Troubleshooting:

@@ -57,6 +57,7 @@

Troubleshooting:

As other videosink choices are not affected by ZOOMFIX, they may or may not be visible to screen-sharing apps. Cairo-based windows created on Linux with “-vs gtksink” are visible to screen-sharing aps without ZOOMFIX; windows on macOS created by “-vs glimagesink” (default choice) and “-vs osximagesink” are also visible.

The “OpenGL renderer” window created on Linux by “-vs glimagesink” sometimes does not close properly when its “close” button is clicked. (this is a GStreamer issue). You may need to terminate uxplay with Ctrl-C to close a “zombie” OpenGl window.

GStreamer issues: To troubleshoot GStreamer execute “export GST_DEBUG=2” to set the GStreamer debug-level environment-variable in the terminal where you will run uxplay, so that you see warning and error messages; (replace “2” by “4” to see much (much) more of what is happening inside GStreamer). Run “gst-inspect-1.0” to see which GStreamer plugins are installed on your system.

+

Some extra GStreamer packages for special plugins may need to be installed (or reinstalled: a user using a Wayland display system as an alternative to X11 reported that after reinstalling Lubuntu 18.4, UxPlay would not work until gstreamer1.0-x was installed, presumably for Wayland’s X11-compatibility mode). Different distributions may break up GStreamer 1.x into packages in different ways; the packages listed above in the build instructions should bring in other required GStreamer packages as dependencies, but will not install all possible plugins.

Usage:

Options:

-n server_name (Default: UxPlay); server_name@_hostname_ will be the name that appears offering AirPlay services to your iPad, iPhone etc, where hostname is the name of the server running uxplay. This will also now be the name shown above the mirror display (X11) window.

@@ -106,8 +107,9 @@

Disclaimer

All the resources in this repository are written using only freely available information from the internet. The code and related resources are meant for educational purposes only. It is the responsibility of the user to make sure all local laws are adhered to.

This project makes use of a third-party GPL library for handling FairPlay. The legal status of that library is unclear. Should you be a representative of Apple and have any objections against the legality of the library and its use in this project, please contact me and I’ll take the appropriate steps.

Given the large number of third-party AirPlay receivers (mostly closed-source) available for purchase, it is my understanding that an open source implementation of the same functionality wouldn’t violate any of Apple’s rights either.

-

RPiPlay Authors (Notes by Florian Draschbacher, RPiPlay creator.)

+

Notes by Florian Draschbacher, RPiPlay creator

(From the https://github.com/FD-/RPiPlay.git repository.)

+

RPiPlay authors

The code in this repository accumulated from various sources over time. Here is my (fdrachbacher) attempt at listing the various authors and the components they created:

-

AirPlay protocol versions

+

AirPlay protocol versions

For multiple reasons, it’s very difficult to clearly define the protocol names and versions of the components that make up the AirPlay streaming system. In fact, it seems like the AirPlay version number used for marketing differs from that used in the actual implementation. In order to tidy up this whole mess a bit, I did a little research that I’d like to summarize here:

The very origin of the AirPlay protocol suite was launched as AirTunes sometime around 2004. It allowed to stream audio from iTunes to an AirPort Express station. Internally, the name of the protocol that was used was RAOP, or Remote Audio Output Protocol. It seems already back then, the protocol involved AES encryption. A public key was needed for encrypting the audio sent to an AirPort Express, and the private key was needed for receiving the protocol (ie used in the AirPort Express to decrypt the stream). Already in 2004, the public key was reverse-engineered, so that third-party sender applications were developed.

Some time around 2008, the protocol was revised and named AirTunes 2. It seems the changes primarily concerned timing. By 2009, the new protocol was reverse-engineered and documented.

diff --git a/README.md b/README.md index ad5009cf..7ba9b6e2 100644 --- a/README.md +++ b/README.md @@ -188,7 +188,8 @@ unpack ("unzip libplist-master.zip ; cd libplist-master"), build/install First make sure that pkgconfig is installed (Homebrew: "brew install pkgconfig" ; MacPorts: "sudo port install pkgconfig" ). (a) with Homebrew: "brew install gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav". This appears to be functionally equivalent -to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies. +to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies. (However, as of November 2021, +Homebrew offers a build of GStreamer for Apple Silicon, which then was not yet available on the offical GStreamer site.) (b) with MacPorts: "sudo port install gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad gstreamer1-gst-libav". The MacPorts GStreamer is built to use X11, so must be run from an XQuartz terminal, can use ZOOMFIX, and needs @@ -258,6 +259,11 @@ where you will run uxplay, so that you see warning and error messages; GStreamer). Run "gst-inspect-1.0" to see which GStreamer plugins are installed on your system. +Some extra GStreamer packages for special plugins may need to be installed (or reinstalled: a user using a Wayland display system as an alternative to X11 +reported that after reinstalling Lubuntu 18.4, UxPlay would not work until gstreamer1.0-x was installed, presumably for Wayland's X11-compatibility mode). +Different distributions may break up GStreamer 1.x into packages in different ways; the packages listed above in the build instructions should bring in +other required GStreamer packages as dependencies, but will not install all possible plugins. + # **Usage:** Options: @@ -470,10 +476,11 @@ This project makes use of a third-party GPL library for handling FairPlay. The l Given the large number of third-party AirPlay receivers (mostly closed-source) available for purchase, it is my understanding that an open source implementation of the same functionality wouldn't violate any of Apple's rights either. -# RPiPlay Authors (Notes by Florian Draschbacher, RPiPlay creator.) - +# Notes by Florian Draschbacher, RPiPlay creator (From the https://github.com/FD-/RPiPlay.git repository.) +## RPiPlay authors + The code in this repository accumulated from various sources over time. Here is my (__fdrachbacher__) attempt at listing the various authors and the components they created: @@ -484,7 +491,7 @@ is my (__fdrachbacher__) attempt at listing the various authors and the componen * **Team XBMC**: Managed to show a black background for OpenMAX video rendering. This code is used in the video renderer. License: GNU GPL * **Alex Izvorski and contributors**: Wrote [h264bitstream](https://github.com/aizvorski/h264bitstream), a library for manipulation h264 streams. Used for reducing delay in the Raspberry Pi video pipeline. Located in the `renderers/h264-bitstream` folder. License: GNU LGPLv2.1 -# AirPlay protocol versions +## AirPlay protocol versions For multiple reasons, it's very difficult to clearly define the protocol names and versions of the components that make up the AirPlay streaming system. In fact, it seems like the AirPlay version number used for marketing differs from that used in the actual implementation. In order to tidy up this whole mess a bit, I did a little research that I'd like to summarize here: diff --git a/README.txt b/README.txt index 26e18694..7a716b29 100644 --- a/README.txt +++ b/README.txt @@ -32,8 +32,8 @@ displayed). The initial connection to the client can be in AirPlay audio mode, or an initial Airplay Mirror connection can be switched to Airplay audio by selecting "Stop Mirroring" in the Screen Mirroring setting (or closing the mirror window) and reconnecting in audio-only AirPlay mode -(this changes back to 44100/2 "Advanced Audio Coding" (AAC-ELD) -compressed (lossy) audio if screen mirroring is (re)started).* +(the audio stream changes back to "Advanced Audio Coding" (AAC-ELD) +compressed (lossy) format if screen mirroring is (re)started).* UxPlay is based on https://github.com/FD-/RPiPlay, with GStreamer integration from https://github.com/antimof/UxPlay. (UxPlay only uses @@ -238,6 +238,9 @@ pkgconfig" ; MacPorts: "sudo port install pkgconfig" ). gst-plugins-bad gst-libav". This appears to be functionally equivalent to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies. + (However, as of November 2021, Homebrew offers a build of GStreamer + for Apple Silicon, which then was not yet available on the offical + GStreamer site.) (b) with MacPorts: "sudo port install gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad @@ -327,6 +330,15 @@ error messages; (replace "2" by "4" to see much (much) more of what is happening inside GStreamer). Run "gst-inspect-1.0" to see which GStreamer plugins are installed on your system. +Some extra GStreamer packages for special plugins may need to be +installed (or reinstalled: a user using a Wayland display system as an +alternative to X11 reported that after reinstalling Lubuntu 18.4, UxPlay +would not work until gstreamer1.0-x was installed, presumably for +Wayland's X11-compatibility mode). Different distributions may break up +GStreamer 1.x into packages in different ways; the packages listed above +in the build instructions should bring in other required GStreamer +packages as dependencies, but will not install all possible plugins. + **Usage:** ========== @@ -577,11 +589,14 @@ closed-source) available for purchase, it is my understanding that an open source implementation of the same functionality wouldn't violate any of Apple's rights either. -RPiPlay Authors (Notes by Florian Draschbacher, RPiPlay creator.) -================================================================= +Notes by Florian Draschbacher, RPiPlay creator +============================================== (From the https://github.com/FD-/RPiPlay.git repository.) +RPiPlay authors +--------------- + The code in this repository accumulated from various sources over time. Here is my (**fdrachbacher**) attempt at listing the various authors and the components they created: @@ -611,7 +626,7 @@ the components they created: `renderers/h264-bitstream` folder. License: GNU LGPLv2.1 AirPlay protocol versions -========================= +------------------------- For multiple reasons, it's very difficult to clearly define the protocol names and versions of the components that make up the AirPlay streaming