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

revisions to README; BSD and GStreamer tips.

Browse Source
This commit is contained in:
fduncanh
2021-11-21 03:08:16 -05:00
parent 881daf545a
commit e610de98e9
3 changed files with 41 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
README.html
View File

@@ -2,12 +2,12 @@
<p>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 <a href="https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol">here</a> and <a href="https://emanuelecozzi.net/docs/airplay2">here</a>).</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 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 <a href="https://www.avahi.org">Avahi</a>, through the avahi-daemon service, and is included in most Linux distributions (this service can also be provided by macOS, iOS or Windows servers).</p>
<p><em><strong>New:</strong> UxPlay &gt; 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 closing the Mirror window and reconnecting in audio-only mode (this changes back to AAC audio if screen mirroring is (re)started).</em></p>
<p>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.</p>
<p>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.</p>
<p>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. VAAPI is preferable, (but don’t use VAAPI with nVidia). 4. Automatic screen orientation.</p>
<h1 id="getting-uxplay">Getting UxPlay:</h1>
<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”.</p>
<p><em>This is a pull request on the original site https://github.com/antimof/UxPlay ; it may or may not ever get committed into the codebase on the antimof site, as that project appears to no longer be active. If the pull request ever gets committed, replace “FDH2” by “antimof” in the above.</em></p>
<h1 id="building-this-version-linux">Building this version (Linux):</h1>
<h1 id="building-this-version-linux-bsd">Building this version (Linux/ *BSD):</h1>
<p>(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for macOS, see below).</p>
<p>You need a C/C++ compiler (e.g. g++) with the standard development libraries installed.</p>
<p>Make sure that cmake&gt;=3.4.1 and pkg-config are also installed: “sudo apt-get install cmake pkg-config”. In a terminal window, change directories to the source directory of the downloaded source code (“UxPlay-master” for zipfile downloads, “UxPlay” for “git clone” downloads), then do</p>
@@ -25,6 +25,7 @@
<p>_If you cannot find a libplist-2.x package that installs on your older distribution, and you don’t wish to upgrade, see the instructions below (in the macOS section) on building libplist from source (you need autoconf, automake, libtool, and may need to also install some libpython*-dev package) but (unlike the statically-linked macOS case) do not uninstall the libplist library after building uxplay; it must remain installed. It is in /usr/local/lib. If uxplay fails to find libplist when you run it, this is probably because /usr/local/lib is not in the library path (by default, this is the case in ubuntu). To fix this, run “sudo ldconfig” (you might also need to create a file /etc/ld.so.conf.d/libplist.conf containing the text “/usr/local/lib” before running ldconfig) to permanently add /usr/local/lib to the library path._</p>
<p><strong>Red Hat, Fedora, CentOS:</strong> (sudo yum install) openssl-devel libplist-devel avahi-compat-libdns_sd-devel (+libX11-devel for ZOOMFIX). The required GStreamer packages are: gstreamer1-devel gstreamer1-plugins-base-devel gstreamer1-libav gstreamer1-plugins-bad-free ( + gstreamer1-vaapi for intel graphics).</p>
<p><strong>OpenSUSE:</strong> (sudo zypper install) libopenssl-devel libplist-devel avahi-compat-mDNSResponder-devel (+ libX11-devel for ZOOMFIX). The required GStreamer packages are: gstreamer-devel gstreamer-plugins-base-devel gstreamer-plugins-libav gstreamer-plugins-bad (+ gstreamer-plugins-vaapi for Intel graphics).</p>
<p><strong>FreeBSD:</strong> (sudo pkg install) libplist gstreamer1, gstreamer1-libav, gstreamer1-plugins, gstreamer1-plugins-* (* = core, good, bad, x, gtk, gl, vulkan, pulse …), (+ gstreamer1-vaapi for Intel graphics). OpenSSL is already installed. “ZOOMFIX” is untested; don’t try to use it unless you need it.</p>
<h1 id="building-this-version-macos">Building this version (macOS):</h1>
<p><strong>(Only tested on Intel X86_64 Macs)</strong></p>
<p><em>Note: A native AirPlay Server feature is included in upcoming macOS 12 Monterey, but UxPlay can run on older macOS systems that will not be able to run Monterey.</em></p>
@@ -45,12 +46,13 @@
<h1 id="troubleshooting"><strong>Troubleshooting:</strong></h1>
<p>If uxplay starts, but stalls after “Initialized server socket(s)” appears, it is probably because a firewall is blocking access to the server on which it is running. If possible, either turn off the firewall to see if that is the problem, or get three consecutive network ports, starting at port n, all three in the range 1024-65535, opened for both tcp and udp, and use “uxplay -p n” (or open UDP 6000, 6001, 6011 TCP 7000,7001,7100 and use “uxplay -p”).</p>
<p>Stalling after “Initialize server socket(s)”, with the server showing as available on the client iPad/iPhone, is almost certainly a firewall problem: one user was unaware that <em>two</em> firewalls (ufw and firewalld) were both active on their system.</p>
<p>Stalling this way, but <em>without</em> the server showing as available on the client, probably means that your network <strong>does not have a running Bonjour/zeroconf DNS-SD server.</strong> On Linux, make sure Avahi is installed, and start the avahi-daemon service (your distribution will document how to do this). Some systems may instead use the mdnsd daemon as an alternative to provide DNS-SD service.</p>
<p>Stalling this way, but <em>without</em> the server showing as available on the client, probably means that your network <strong>does not have a running Bonjour/zeroconf DNS-SD server.</strong> On Linux, make sure Avahi is installed, and start the avahi-daemon service (your distribution will document how to do this). Some systems may instead use the mdnsd daemon as an alternative to provide DNS-SD service. (FreeBSD offers both alternatives, but only Avahi was tested: one of the steps needed for getting Avahi running on this system is to edit /usr/local/etc/avahi/avahi-daemon.conf to uncomment a line for airplay support.)</p>
<p>For other problems after a connection is made, use “uxplay -d” (debug log option) to see what is happening. <strong>Such problems are usually due to a GStreamer plugin that doesn’t work on your system</strong>: (by default, GStreamer uses an algorithm to guess what is the “best” plugin to use on your system). If you use an nVidia graphics card, make sure that the gstreamer1.0-vaapi plugin for Intel graphics is <em>NOT</em> installed (<strong>uninstall it</strong> if it is installed!). (You can test for this by explicitly choosing the GStreamer videosink with option “-vs ximagesink” or “-vs xvimagesink”, to see if this fixes the problem, or “-vs vaapisink” to see if this reproduces the problem.)</p>
<p>You can try to fix audio problems by using the “-as <em>audiosink</em>” option to choose the GStreamer audiosink , rather than have autoaudiosink pick one for you. The command “gst_inspect-1.0 | grep Sink | grep Audio” " will show you which audiosinks are available on your system. (Replace “Audio” by “Video” to see videosinks). Some possible audiosinks are pulsesink, alsasink, osssink, oss4sink, and osxaudiosink (macOS).</p>
<p>If you ran cmake with “-DZOOMFIX=ON”, check if the problem is still there without ZOOMFIX. ZOOMFIX is only applied to the default videosink choice (“autovideosink”) and the two X11 videosinks “ximagesink” and “xvimagesink”. ZOOMFIX is only designed for these last two; if autovideosink chooses a different videosink, ZOOMFIX is now ignored. If you are using the X11 windowing system (standard on Linux), and have trouble with screen-sharing on Zoom, use ZOOMFIX and “-vs xvimagesink” (or “-vs ximagesink” if the previous choice doesn’t work).</p>
<p>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.</p>
<p>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.</p>
<p><strong>GStreamer issues:</strong> 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.</p>
<h1 id="usage"><strong>Usage:</strong></h1>
<p>Options:</p>
<p><strong>-n server_name</strong> (Default: UxPlay); server_name@_hostname_ will be the name that appears offering AirPlay services to your iPad, iPhone etc, where <em>hostname</em> is the name of the server running uxplay. This will also now be the name shown above the mirror display (X11) window.</p>

17
README.md
View File

@@ -28,7 +28,7 @@ UxPlay is based on https://github.com/FD-/RPiPlay, with GStreamer integration fr
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.
Tested on Ubuntu 20.04, Linux Mint 20.2, OpenSUSE 15.3, macOS 10.15, FreeBSD 13.0.
Features:
1. Based on Gstreamer.
@@ -48,7 +48,7 @@ get committed into the codebase on the antimof site, as that
project appears to no longer be active.
If the pull request ever gets committed, replace "FDH2" by "antimof" in the above.*
# Building this version (Linux):
# Building this version (Linux/ *BSD):
(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for macOS, see below).
@@ -98,6 +98,9 @@ avahi-compat-mDNSResponder-devel (+ libX11-devel for ZOOMFIX). The required
GStreamer packages are:
gstreamer-devel gstreamer-plugins-base-devel gstreamer-plugins-libav gstreamer-plugins-bad (+ gstreamer-plugins-vaapi for Intel graphics).
**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).
OpenSSL is already installed. "ZOOMFIX" is untested; don't try to use it unless you need it.
# Building this version (macOS):
@@ -195,6 +198,9 @@ probably means that your network **does not have a running Bonjour/zeroconf DNS-
On Linux, make sure Avahi is installed,
and start the avahi-daemon service (your distribution will document how to do this).
Some systems may instead use the mdnsd daemon as an alternative to provide DNS-SD service.
(FreeBSD offers both alternatives, but only Avahi was tested: one of the steps needed for
getting Avahi running on this system is to edit /usr/local/etc/avahi/avahi-daemon.conf to
uncomment a line for airplay support.)
For other problems after a connection is made, use "uxplay -d " (debug log option) to see what is happening.
**Such problems are usually due to a GStreamer plugin that doesn't work on your system**: (by default,
@@ -226,6 +232,13 @@ Cairo-based windows created on Linux with "-vs gtksink" are visible to screen-sh
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.
# **Usage:**
Options:

25
README.txt
View File

@@ -37,7 +37,7 @@ 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.
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
@@ -57,8 +57,8 @@ into the codebase on the antimof site, as that project appears to no
longer be active. If the pull request ever gets committed, replace
"FDH2" by "antimof" in the above.*
Building this version (Linux):
==============================
Building this version (Linux/ \*BSD):
=====================================
(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for
macOS, see below).
@@ -129,6 +129,12 @@ required GStreamer packages are: gstreamer-devel
gstreamer-plugins-base-devel gstreamer-plugins-libav
gstreamer-plugins-bad (+ gstreamer-plugins-vaapi for Intel graphics).
**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). OpenSSL
is already installed. "ZOOMFIX" is untested; don't try to use it unless
you need it.
Building this version (macOS):
==============================
@@ -248,7 +254,11 @@ client, probably means that your network **does not have a running
Bonjour/zeroconf DNS-SD server.** On Linux, make sure Avahi is
installed, and start the avahi-daemon service (your distribution will
document how to do this). Some systems may instead use the mdnsd daemon
as an alternative to provide DNS-SD service.
as an alternative to provide DNS-SD service. (FreeBSD offers both
alternatives, but only Avahi was tested: one of the steps needed for
getting Avahi running on this system is to edit
/usr/local/etc/avahi/avahi-daemon.conf to uncomment a line for airplay
support.)
For other problems after a connection is made, use "uxplay -d" (debug
log option) to see what is happening. **Such problems are usually due to
@@ -288,6 +298,13 @@ 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.
**Usage:**
==========