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

UxPlay 1.64: -h, manpage and README updates

Browse Source
This commit is contained in:
F. Duncanh
2023-04-23 19:25:02 -04:00
parent 16e5b4ae06
commit 67d61c2fc9
6 changed files with 262 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
README.html
View File

@@ -1,6 +1,6 @@
<h1
id="uxplay-1.63-airplay-mirror-and-airplay-audio-server-for-linux-macos-and-unix-now-also-runs-on-windows.">UxPlay
1.63: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix
id="uxplay-1.64-airplay-mirror-and-airplay-audio-server-for-linux-macos-and-unix-now-also-runs-on-windows.">UxPlay
1.64: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix
(now also runs on Windows).</h1>
<h3
id="now-developed-at-the-github-site-httpsgithub.comfdh2uxplay-where-all-user-issues-should-be-posted.">Now
@@ -83,12 +83,14 @@ posts updates pulled from the new main <a
href="https://github.com/FDH2/UxPlay">UxPlay site</a>).</p>
<p>UxPlay is tested on a number of systems, including (among others)
Debian 10.11 “Buster” and 11.2 “Bullseye”, Ubuntu 20.04 LTS and 22.04.1
LTS, Linux Mint 20.3, Pop!_OS 22.04 (NVIDIA edition), Rocky Linux 8.6 (a
CentOS successor), Fedora 36, OpenSUSE 15.4, Arch Linux 22.10, macOS
12.3 (Intel and M1), FreeBSD 13.1, Windows 10 and 11 (64 bit).</p>
LTS, (also Ubuntu derivatives Linux Mint 20.3, Pop!_OS 22.04 (NVIDIA
edition)), Rocky Linux 9.1 (a CentOS successor), Fedora 36, OpenSUSE
15.4, Arch Linux 22.10, macOS 13.3 (Intel and M2), FreeBSD 13.2, Windows
10 and 11 (64 bit).</p>
<p>On Raspberry Pi 4 model B, it is tested on Raspberry Pi OS (Bullseye)
(32- and 64-bit), Ubuntu 22.10, Manjaro RPi4 23.02, and (without
hardware video decoding) on OpenSUSE 15.4.</p>
(32- and 64-bit), Ubuntu 22.04 and 22.10, Manjaro RPi4 23.02, and
(without hardware video decoding) on OpenSUSE 15.4. Also tested on
Raspberry Pi 3 model B+.</p>
<p>Its main use is to act like an AppleTV for screen-mirroring (with
audio) of iOS/iPadOS/macOS clients (iPhone, iPod Touch, iPad, Mac
computers) on the server display of a host running Linux, macOS, or
@@ -356,6 +358,14 @@ gl, vulkan, pulse, v4l2, …), (+ gstreamer1-vaapi for Intel
graphics).</p></li>
</ul>
<h3 id="starting-and-running-uxplay">Starting and running UxPlay</h3>
<p>Since UxPlay-1.64, UxPlay can be started with options read from a
configuration file, which will be the first found of (1) a file with a
path given by environment variable <code>$UXPLAYRC</code>, (2)
<code>~/.uxplayrc</code> in the user’s home directory (“~”), (3)
<code>~/.config/uxplayrc</code>. The format is one option per line,
omitting the initial <code>"-"</code> of the command-line option. Lines
in the configuration file beginning with <code>"#"</code> are treated as
comments and ignored.</p>
<p><strong>Run uxplay in a terminal window</strong>. On some systems,
you can toggle into and out of fullscreen mode with F11 or (held-down
left Alt)+Enter keys. Use Ctrl-C (or close the window) to terminate it
@@ -381,31 +391,37 @@ client drops the connection; since UxPlay-1.58, the option
requests a connection, it removes the current client and takes
over.</p></li>
<li><p>In Mirror mode, GStreamer has a choice of <strong>two</strong>
methods to play video with its accompanying audio: the default mode
(“sync=false”) just plays both streams as soon as possible after they
arrive, and the (“sync=true”) mode used by the <code>-vsync</code>
option (first introduced in UxPlay-1.63), uses the timestamps in the
streams sent by the Airplay client to play audio and video frames
together at the correct time. For playing long video sequences on any
UxPlay server, use the -vsync option: this may become the default in
future UxPlay releases.</p></li>
methods to play video with its accompanying audio: prior to UxPlay-1.64,
the video and audio streams were both played as soon as possible after
they arrived (the GStreamer “<em>sync=false</em>” method), with a
GStreamer internal clock used to try to keep them synchronized.
<strong>Starting with UxPlay-1.64, the other method (GStreamer’s
“<em>sync-true</em>” mode), which uses timestamps in the audio and video
streams sent by the client, is the new default</strong>. On
low-decoding-power UxPlay hosts (such as Raspberry Pi 3 models) this
will drop video frames that cannot be decoded in time to play with the
audio, making the video jerky, but still synchronized.</p></li>
</ul>
<p>Provided the UxPlay host can process the video sufficently fast, the
default “sync=false” mode seems to work well at keeping video and audio
synchronized, but on lower decoding-power systems (e.g. Raspberry Pi 3
Model B+), the -vsync option is definitely needed: this will drop video
frames that do not get decoded in time to match the audio, perhaps
making the video “jerky”, but keeping it synchronized with the
audio.</p>
<p>The older method which does not drop late video frames worked well on
more powerful systems, and is still available with the UxPlay option
“<code>-vsync no</code>”; this method is adapted to “live streaming”,
and may be better when Using UxPlay as a second monitor for a Mac
computer, for example, while the new default timestamp-based method is
best for watching a video, to keep lip movements and voices
synchronized. (Without use of timestamps, video will eventually lag
behind audio if it cannot be decoded fast enough: hardware-accelerated
video-decoding helped to prevent this previously when timestamps were
not being used.)</p>
<ul>
<li>In Audio-only mode the “sync=false” option is also the default, but
if you want to keep the audio playing on the server synchronized with
the video on the client, use the <code>-async</code> option. (An example
might be if you want to follow the Apple Music lyrics on the client
while listening to superior sound on the UxPlay server). This delays the
video on the client to match audio on the server, so leads to a slight
delay before a pause or track-change initiated on the client takes
effect on the audio played by the server.</li>
<li>In Audio-only mode the GStreamer “sync=false” mode (not using
timestamps) is still the default, but if you want to keep the audio
playing on the server synchronized with the video showing on the client,
use the <code>-async</code> timestamp-based option. (An example might be
if you want to follow the Apple Music lyrics on the client while
listening to superior sound on the UxPlay server). This delays the video
on the client to match audio on the server, so leads to a slight delay
before a pause or track-change initiated on the client takes effect on
the audio played by the server.</li>
</ul>
<p>The -vsync and -async options also allow an optional positive (or
negative) audio-delay adjustment in <em>milliseconds</em> for
@@ -415,8 +431,8 @@ fine-tuning : <code>-vsync 20.5</code> delays audio relative to video by
<li><p>you may find video is improved by the setting -fps 60 that allows
some video to be played at 60 frames per second. (You can see what
framerate is actually streaming by using -vs fpsdisplaysink, and/or
-FPSdata.) When using this, you probably should use the -vsync
option.</p></li>
-FPSdata.) When using this, you should use the default timestamp-based
synchronization option <code>-vsync</code>.</p></li>
<li><p>Since UxPlay-1.54, you can display the accompanying “Cover Art”
from sources like Apple Music in Audio-Only (ALAC) mode: run
“<code>uxplay -ca &lt;name&gt; &amp;</code>” in the background, then run
@@ -438,10 +454,9 @@ instructions for Raspberry Pi (tested on R Pi 4 model B 8GB and R Pi 3
model B+)</strong>:</h3>
<ul>
<li><p>If you use the software-only (h264) video-decoding UxPlay option
<code>-avdec</code>, you also need option <code>-vsync</code>to keep
audio and video synchronized (<code>-vsync</code> is a new feature;
before it was introduced, software decoding on the Pi was not
viable.)</p></li>
<code>-avdec</code>, it now works better that earlier, with the new
default timestamp-based synchronization to keep audio and video
synchronized.</p></li>
<li><p>For best performance, the Raspberry Pi needs the GStreamer
Video4linux2 plugin to use its Broadcom GPU hardware for decoding h264
video. This needs the bcm2835_codec kernel module which is maintained
@@ -457,9 +472,8 @@ cannot use the decoding firmware in the GPU.</strong></p></li>
Raspberry Pi OS, use a similar tool on other distributions) to allocate
sufficient memory for the GPU (on R. Pi 3 model B+, the maximum (256MB)
is suggested). Even with GPU video decoding, some frames may be dropped
by the lower-power 3 B+, so the -vsync option (introduced in
UxPlay-1.63) that uses timestamps to synchronize audio and video is
needed.</p>
by the lower-power 3 B+ to keep audio and video synchronized using
timestamps.</p>
<ul>
<li>The plugin in the latest GStreamer-1.22 release works well, but
older releases of GStreamer will not work unless patched with backports
@@ -470,7 +484,7 @@ href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches"
with instructions in the UxPlay Wiki</a>.</li>
</ul>
<p>The basic uxplay options for R Pi are
<code>uxplay -vsync [-vs &lt;videosink&gt;]</code>. The choice
<code>uxplay [-vs &lt;videosink&gt;]</code>. The choice
<code>&lt;videosink&gt;</code> = <code>glimagesink</code> is sometimes
useful. On a system without X11 (like R Pi OS Lite) with framebuffer
video, use <code>&lt;videosink&gt;</code> = <code>kmssink</code>. With
@@ -480,10 +494,10 @@ hardware video decoding, an option <code>-v4l2</code> may be useful: for
convenience, this also comes combined with various videosink options as
<code>-rpi</code>, <code>-rpigl</code> <code>-rpifb</code>,
<code>-rpiwl</code>, respectively provided for X11, X11 with OpenGL,
framebuffer, and Wayland systems. You may find that just
“<code>uxplay -vsync</code>”, (<em>without</em> <code>-v4l2</code> or
framebuffer, and Wayland systems. <strong>You may find that just
“<code>uxplay</code>”, (<em>without</em> <code>-v4l2</code> or
<code>-rpi*</code> options, which lets GStreamer try to find the best
video solution by itself) provides the best results (the
video solution by itself) provides the best results</strong> (the
<code>-rpi*</code> options may be removed in a future release of
UxPlay.)</p>
<ul>
@@ -723,15 +737,19 @@ the mirror display (X11) window.</p>
<p><strong>-nh</strong> Do not append “<span class="citation"
data-cites="_hostname_">@_hostname_</span>” at the end of the AirPlay
server name.</p>
<p><strong>-vsync [x]</strong> (In Mirror mode:) this option uses
timestamps to synchronize audio with video on the server, with an
optional audio delay in (decimal) milliseconds (<em>x</em> = “20.5”
means 0.0205 seconds delay: positive or negative delays less than a
second are allowed.) It is needed on low-power systems such as Raspberry
Pi without hardware video decoding. Standard desktop systems seem to
work well without this (streaming without use of timestamps was the only
behavior prior to UxPlay 1.63), but you may wish to use it there too.
(It may become the default in future releases.)</p>
<p><strong>-vsync [x]</strong> (In Mirror mode:) this option
(<strong>now the default</strong>) uses timestamps to synchronize audio
with video on the server, with an optional audio delay in (decimal)
milliseconds (<em>x</em> = “20.5” means 0.0205 seconds delay: positive
or negative delays less than a second are allowed.) It is needed on
low-power systems such as Raspberry Pi without hardware video
decoding.</p>
<p><strong>-vsync no</strong> (In Mirror mode:) this switches off
timestamp-based audio-video synchronization, restoring the default
behavior prior to UxPlay-1.64. Standard desktop systems seem to work
well without use of timestamps: this mode is appropriate for “live
streaming” such as using UxPlay as a second monitor for a mac computer,
or monitoring a webcam; with it, no video frames are dropped.</p>
<p><strong>-async [x]</strong> (In Audio-Only (ALAC) mode:) this option
uses timestamps to synchronize audio on the server with video on the
client, with an optional audio delay in (decimal) milliseconds
@@ -744,6 +762,10 @@ principle be mitigated by using the <code>-al</code> audio latency
setting to change the latency (default 0.25 secs) that the server
reports to the client, but at present changing this does not seem to
have any effect</em>.</p>
<p><strong>-async no</strong>. This is the still the default behavior in
Audio-only mode, but this option may be useful as a command-line option
to switch of a <code>-async</code> option set in a “uxplayrc”
configuration file.</p>
<p><strong>-s wxh</strong> (e.g. -s 1920x1080 , which is the default )
sets the display resolution (width and height, in pixels). (This may be
a request made to the AirPlay client, and perhaps will not be the final
@@ -1056,8 +1078,8 @@ module that is not in the standard Linux kernel (it is available in
Raspberry Pi OS, Ubuntu and Manjaro).</p>
<ul>
<li><strong>If this kernel module is not available in your Raspberry Pi
operating system, or if GStreamer &lt; 1.22 is not patched, use options
<code>-avdec -vsync</code> for software h264-decoding.</strong></li>
operating system, or if GStreamer &lt; 1.22 is not patched, use option
<code>-avdec</code> for software h264-decoding.</strong></li>
</ul>
<p>Sometimes “autovideosink” may select the OpenGL renderer
“glimagesink” which may not work correctly on your system. Try the
@@ -1207,6 +1229,10 @@ the client by the AirPlay server) to be set.</p>
<p>The “features” code and other settings are set in
<code>UxPlay/lib/dnssdint.h</code>.</p>
<h1 id="changelog">Changelog</h1>
<p>1.64 2023-04-23 Timestamp-based synchronization of audio and video is
now the default in Mirror mode. (Use “-vsync no” to restore previous
behavior.) A configuration file can now be used for startup options.
Also some internal cleanups and a minor bugfix that fixes #192.</p>
<p>1.63 2023-02-12 Reworked audio-video synchronization, with new
options -vsync (for Mirror mode) and -async (for Audio-Only mode, to
sync with client video). Option -vsync makes software h264 decoding of

89
README.md
View File

@@ -1,4 +1,4 @@
# UxPlay 1.63: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix (now also runs on Windows).
# UxPlay 1.64: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix (now also runs on Windows).
### Now developed at the GitHub site [https://github.com/FDH2/UxPlay](https://github.com/FDH2/UxPlay) (where all user issues should be posted).
@@ -60,11 +60,12 @@ development, but periodically posts updates pulled from the new
main [UxPlay site](https://github.com/FDH2/UxPlay)).
UxPlay is tested on a number of systems, including (among others) Debian 10.11 "Buster" and 11.2 "Bullseye",
Ubuntu 20.04 LTS and 22.04.1 LTS, Linux Mint 20.3, Pop!\_OS 22.04 (NVIDIA edition), Rocky Linux 8.6 (a CentOS successor), Fedora 36,
OpenSUSE 15.4, Arch Linux 22.10, macOS 12.3 (Intel and M1), FreeBSD 13.1, Windows 10 and 11 (64 bit).
Ubuntu 20.04 LTS and 22.04.1 LTS, (also Ubuntu derivatives Linux Mint 20.3, Pop!\_OS 22.04 (NVIDIA edition)),
Rocky Linux 9.1 (a CentOS successor), Fedora 36, OpenSUSE 15.4, Arch Linux 22.10, macOS 13.3 (Intel and M2),
FreeBSD 13.2, Windows 10 and 11 (64 bit).
On Raspberry Pi 4 model B, it is tested on Raspberry Pi OS (Bullseye) (32- and 64-bit), Ubuntu 22.10, Manjaro RPi4 23.02, and (without hardware
video decoding) on OpenSUSE 15.4.
On Raspberry Pi 4 model B, it is tested on Raspberry Pi OS (Bullseye) (32- and 64-bit), Ubuntu 22.04 and 22.10, Manjaro RPi4 23.02,
and (without hardware video decoding) on OpenSUSE 15.4. Also tested on Raspberry Pi 3 model B+.
Its main use is to act like an AppleTV for screen-mirroring (with audio) of iOS/iPadOS/macOS clients
(iPhone, iPod Touch, iPad, Mac computers) on the server display
@@ -306,6 +307,11 @@ for Intel graphics).
### Starting and running UxPlay
Since UxPlay-1.64, UxPlay can be started with options read from a configuration file, which will be the first found of
(1) a file with a path given by environment variable `$UXPLAYRC`, (2) ``~/.uxplayrc`` in the user's home
directory ("~"), (3) ``~/.config/uxplayrc``. The format is one option per line, omitting the initial ``"-"`` of
the command-line option. Lines in the configuration file beginning with `"#"` are treated as comments and ignored.
**Run uxplay in a terminal window**. On some systems, you can toggle into and out of fullscreen mode
with F11 or (held-down left Alt)+Enter keys. Use Ctrl-C (or close the window)
to terminate it when done. If the UxPlay server is not seen by the
@@ -326,21 +332,26 @@ help with this or other problems.
its current client until that client drops the connection; since UxPlay-1.58, the option `-nohold` modifies this
behavior so that when a new client requests a connection, it removes the current client and takes over.
* In Mirror mode, GStreamer has a choice of **two** methods to play video with its accompanying audio: the default
mode ("sync=false") just plays both streams as soon as possible after they arrive, and the ("sync=true") mode
used by the `-vsync` option (first introduced in UxPlay-1.63), uses the
timestamps in the streams sent by the Airplay client to play audio and video frames together at the correct time.
For playing long video sequences
on any UxPlay server, use the -vsync option: this may become the default in future UxPlay releases.
* In Mirror mode, GStreamer has a choice of **two** methods to play video with its accompanying audio: prior to UxPlay-1.64,
the video and audio streams were both played as soon as possible after they arrived (the GStreamer "_sync=false_" method), with
a GStreamer internal clock used to try to keep them synchronized. **Starting with UxPlay-1.64, the other method
(GStreamer's "_sync-true_" mode), which uses timestamps in the audio and video streams sent by the client, is the new default**.
On low-decoding-power UxPlay hosts (such as Raspberry Pi 3 models) this will drop video frames that cannot be decoded in time
to play with the audio, making the video jerky, but still synchronized.
Provided the UxPlay host can process the video sufficently fast, the default "sync=false" mode seems to work
well at keeping video and audio synchronized, but on lower decoding-power systems (e.g. Raspberry Pi 3 Model B+),
the -vsync option is definitely needed: this will drop video frames that do not get decoded in
time to match the audio, perhaps making the video "jerky", but keeping it synchronized with the audio.
The older method which does not drop late video frames
worked well on more powerful systems, and is still available with the UxPlay option "`-vsync no`"; this method is adapted
to "live streaming", and may be better when Using UxPlay as a second monitor for a Mac computer, for example, while the new default
timestamp-based method is best for watching a video, to keep lip movements and voices synchronized. (Without use of timestamps,
video will eventually lag behind audio if it cannot be decoded fast enough: hardware-accelerated video-decoding helped to prevent this
previously when timestamps were not being used.)
* In Audio-only mode the "sync=false" option is also the default, but if you want to keep the audio playing on the server synchronized
with the video on the client, use the `-async` option. (An example might be if you want to follow the Apple Music lyrics on the client
while listening to superior sound on the UxPlay server). This delays the video on the client to match audio on the server, so leads to
* In Audio-only mode the GStreamer "sync=false" mode (not using timestamps) is still the default, but if you want to keep the audio
playing on the server synchronized with the video showing on the client, use the `-async` timestamp-based option. (An example might be
if you want to follow the Apple Music lyrics on the client while listening to superior sound on the UxPlay server). This
delays the video on the client to match audio on the server, so leads to
a slight delay before a pause or track-change initiated on the client takes effect on the audio played by the server.
The -vsync and -async options
@@ -349,7 +360,7 @@ delays audio relative to video by 0.0205 secs; a negative value advances it.)
* you may find video is improved by the setting -fps 60 that allows some video to be played at 60 frames
per second. (You can see what framerate is actually streaming by using -vs fpsdisplaysink, and/or -FPSdata.)
When using this, you probably should use the -vsync option.
When using this, you should use the default timestamp-based synchronization option `-vsync`.
* Since UxPlay-1.54, you can display the accompanying "Cover Art" from sources like Apple Music in Audio-Only (ALAC) mode:
run "`uxplay -ca <name> &`" in the background, then run a image viewer with an autoreload feature: an example
@@ -367,9 +378,8 @@ See [Usage](#usage) for more run-time options.
### **Special instructions for Raspberry Pi (tested on R Pi 4 model B 8GB and R Pi 3 model B+)**:
* If you use the software-only (h264) video-decoding UxPlay option `-avdec`, you also need
option `-vsync`to keep audio and video synchronized (`-vsync` is a new feature; before
it was introduced, software decoding on the Pi was not viable.)
* If you use the software-only (h264) video-decoding UxPlay option `-avdec`, it now works
better that earlier, with the new default timestamp-based synchronization to keep audio and video synchronized.
* For best performance, the Raspberry Pi needs the GStreamer Video4linux2 plugin to use
its Broadcom GPU hardware for decoding h264 video. This needs the bcm2835_codec kernel module
@@ -381,24 +391,24 @@ provide it: **without this kernel module, UxPlay cannot use the decoding firmwar
For use of the GPU, use raspi-config "Performance Options" (on Raspberry Pi OS, use a similar tool on other
distributions) to allocate sufficient memory for the GPU (on R. Pi 3 model B+, the maximum (256MB) is suggested).
Even with GPU video decoding, some frames may be dropped by the lower-power 3 B+, so the -vsync option
(introduced in UxPlay-1.63) that uses timestamps to synchronize audio and video is needed.
Even with GPU video decoding, some frames may be dropped by the lower-power 3 B+ to keep audio and video synchronized
using timestamps.
* The plugin in the latest GStreamer-1.22 release works well, but older releases of GStreamer will not
work unless patched with backports from GStreamer-1.22. Raspberry Pi OS (Bullseye) now has a
working backport. For a fuller backport, or for other distributions, patches for the GStreamer Video4Linux2 plugin
are [available with instructions in the UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches).
The basic uxplay options for R Pi are ```uxplay -vsync [-vs <videosink>]```. The
The basic uxplay options for R Pi are ```uxplay [-vs <videosink>]```. The
choice `<videosink>` = ``glimagesink`` is sometimes useful.
On a system without X11 (like R Pi OS Lite) with framebuffer video, use `<videosink>` = ``kmssink``.
With the Wayland video compositor, use `<videosink>` = ``waylandsink``. When using the Video4Linux2
plugin to access hardware video decoding, an option `-v4l2` may be useful: for convenience, this also comes
combined with various videosink options as `-rpi`, ``-rpigl`` ``-rpifb``, ```-rpiwl```, respectively
provided for X11, X11 with OpenGL, framebuffer, and Wayland systems.
You may find that just "`uxplay -vsync`", (_without_ ``-v4l2`` or ```-rpi*``` options, which lets GStreamer
**You may find that just "`uxplay`", (_without_ ``-v4l2`` or ```-rpi*``` options, which lets GStreamer
try to find the best video solution by itself)
provides the best results (the `-rpi*` options may be removed in a future release of UxPlay.)
provides the best results** (the `-rpi*` options may be removed in a future release of UxPlay.)
* If you are using Raspberry Pi OS (Bullseye) with Video4Linux2 from unpatched GStreamer-1.18.4, you
need the `-bt709` option with UxPlay-1.56 or later.
@@ -590,12 +600,14 @@ Options:
**-nh** Do not append "@_hostname_" at the end of the AirPlay server name.
**-vsync [x]** (In Mirror mode:) this option uses timestamps to synchronize audio with video on the server,
**-vsync [x]** (In Mirror mode:) this option (**now the default**) uses timestamps to synchronize audio with video on the server,
with an optional audio delay in (decimal) milliseconds (_x_ = "20.5" means 0.0205 seconds delay: positive or
negative delays less than a second are allowed.) It is needed on low-power systems such as Raspberry Pi without hardware
video decoding. Standard desktop systems seem to work well without this (streaming without use of timestamps
was the only behavior prior to UxPlay 1.63), but you may wish to use it there too. (It may become the default in future releases.)
video decoding.
**-vsync no** (In Mirror mode:) this switches off timestamp-based audio-video synchronization, restoring the default behavior prior to
UxPlay-1.64. Standard desktop systems seem to work well without use of timestamps: this mode is appropriate for "live streaming" such as
using UxPlay as a second monitor for a mac computer, or monitoring a webcam; with it, no video frames are dropped.
**-async [x]** (In Audio-Only (ALAC) mode:) this option uses timestamps to synchronize audio on the server with video on the client,
with an optional audio delay in (decimal) milliseconds (_x_ = "20.5" means 0.0205 seconds delay: positive or
@@ -605,6 +617,8 @@ Options:
immediately. _This might in principle be mitigated by using the `-al` audio latency setting to change the latency (default 0.25 secs)
that the server reports to the client, but at present changing this does not seem to have any effect_.
**-async no**. This is the still the default behavior in Audio-only mode, but this option may be useful as a command-line option to switch of a
`-async` option set in a "uxplayrc" configuration file.
**-s wxh** (e.g. -s 1920x1080 , which is the default ) sets the display resolution (width and height,
in pixels). (This may be a
@@ -865,13 +879,14 @@ to guess what are the "best" plugins to use on your system).
A different reason for no audio occurred when a user with a firewall only opened two udp network
ports: **three** are required (the third one receives the audio data).
**Raspberry Pi** devices work best with hardware GPU h264 video decoding if the Video4Linux2 plugin in GStreamer v1.20.x or earlier has been patched
(see the UxPlay [Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches) for patches).
This is fixed in GStreamer-1.22, and by backport patches from this in distributions such as Raspberry Pi OS (Bullseye): **use option `-bt709` with the
GStreamer-1.18.4 from Raspberry Pi OS**..
**Raspberry Pi** devices work best with hardware GPU h264 video decoding if the Video4Linux2 plugin in GStreamer v1.20.x or earlier has
been patched (see the UxPlay [Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches) for patches).
This is fixed in GStreamer-1.22, and by backport patches from this in distributions such as Raspberry Pi OS (Bullseye): **use option `-bt709`
with the GStreamer-1.18.4 from Raspberry Pi OS**..
This also needs the bcm2835-codec kernel module that is not in the standard Linux kernel (it is available in Raspberry Pi OS, Ubuntu and Manjaro).
* **If this kernel module is not available in your Raspberry Pi operating system, or if GStreamer < 1.22 is not patched, use options `-avdec -vsync` for software h264-decoding.**
* **If this kernel module is not available in your Raspberry Pi operating system, or if GStreamer < 1.22 is not patched, use option `-avdec`
for software h264-decoding.**
Sometimes "autovideosink" may select the OpenGL renderer "glimagesink" which
may not work correctly on your system. Try the options "-vs ximagesink" or
@@ -991,6 +1006,10 @@ tvOS 12.2.1); it seems that the use of "legacy" protocol just requires bit 27 (l
The "features" code and other settings are set in `UxPlay/lib/dnssdint.h`.
# Changelog
1.64 2023-04-23 Timestamp-based synchronization of audio and video is now the default in Mirror mode.
(Use "-vsync no" to restore previous behavior.) A configuration file can now be used
for startup options. Also some internal cleanups and a minor bugfix that fixes #192.
1.63 2023-02-12 Reworked audio-video synchronization, with new options -vsync (for Mirror mode) and
-async (for Audio-Only mode, to sync with client video). Option -vsync makes software
h264 decoding of streamed videos with option -avdec viable on some recent Raspberry Pi models.

131
README.txt
View File

@@ -1,4 +1,4 @@
# UxPlay 1.63: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix (now also runs on Windows).
# UxPlay 1.64: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix (now also runs on Windows).
### Now developed at the GitHub site <https://github.com/FDH2/UxPlay> (where all user issues should be posted).
@@ -78,13 +78,15 @@ pulled from the new main [UxPlay site](https://github.com/FDH2/UxPlay)).
UxPlay is tested on a number of systems, including (among others) Debian
10.11 "Buster" and 11.2 "Bullseye", Ubuntu 20.04 LTS and 22.04.1 LTS,
Linux Mint 20.3, Pop!\_OS 22.04 (NVIDIA edition), Rocky Linux 8.6 (a
CentOS successor), Fedora 36, OpenSUSE 15.4, Arch Linux 22.10, macOS
12.3 (Intel and M1), FreeBSD 13.1, Windows 10 and 11 (64 bit).
(also Ubuntu derivatives Linux Mint 20.3, Pop!\_OS 22.04 (NVIDIA
edition)), Rocky Linux 9.1 (a CentOS successor), Fedora 36, OpenSUSE
15.4, Arch Linux 22.10, macOS 13.3 (Intel and M2), FreeBSD 13.2, Windows
10 and 11 (64 bit).
On Raspberry Pi 4 model B, it is tested on Raspberry Pi OS (Bullseye)
(32- and 64-bit), Ubuntu 22.10, Manjaro RPi4 23.02, and (without
hardware video decoding) on OpenSUSE 15.4.
(32- and 64-bit), Ubuntu 22.04 and 22.10, Manjaro RPi4 23.02, and
(without hardware video decoding) on OpenSUSE 15.4. Also tested on
Raspberry Pi 3 model B+.
Its main use is to act like an AppleTV for screen-mirroring (with audio)
of iOS/iPadOS/macOS clients (iPhone, iPod Touch, iPad, Mac computers) on
@@ -354,6 +356,14 @@ installed, depending on how your audio is set up.
### Starting and running UxPlay
Since UxPlay-1.64, UxPlay can be started with options read from a
configuration file, which will be the first found of (1) a file with a
path given by environment variable `$UXPLAYRC`, (2) `~/.uxplayrc` in the
user's home directory ("\~"), (3) `~/.config/uxplayrc`. The format is
one option per line, omitting the initial `"-"` of the command-line
option. Lines in the configuration file beginning with `"#"` are treated
as comments and ignored.
**Run uxplay in a terminal window**. On some systems, you can toggle
into and out of fullscreen mode with F11 or (held-down left Alt)+Enter
keys. Use Ctrl-C (or close the window) to terminate it when done. If the
@@ -378,28 +388,34 @@ below for help with this or other problems.
connection, it removes the current client and takes over.
- In Mirror mode, GStreamer has a choice of **two** methods to play
video with its accompanying audio: the default mode ("sync=false")
just plays both streams as soon as possible after they arrive, and
the ("sync=true") mode used by the `-vsync` option (first introduced
in UxPlay-1.63), uses the timestamps in the streams sent by the
Airplay client to play audio and video frames together at the
correct time. For playing long video sequences on any UxPlay server,
use the -vsync option: this may become the default in future UxPlay
releases.
video with its accompanying audio: prior to UxPlay-1.64, the video
and audio streams were both played as soon as possible after they
arrived (the GStreamer "*sync=false*" method), with a GStreamer
internal clock used to try to keep them synchronized. **Starting
with UxPlay-1.64, the other method (GStreamer's "*sync-true*" mode),
which uses timestamps in the audio and video streams sent by the
client, is the new default**. On low-decoding-power UxPlay hosts
(such as Raspberry Pi 3 models) this will drop video frames that
cannot be decoded in time to play with the audio, making the video
jerky, but still synchronized.
Provided the UxPlay host can process the video sufficently fast, the
default "sync=false" mode seems to work well at keeping video and audio
synchronized, but on lower decoding-power systems (e.g. Raspberry Pi 3
Model B+), the -vsync option is definitely needed: this will drop video
frames that do not get decoded in time to match the audio, perhaps
making the video "jerky", but keeping it synchronized with the audio.
The older method which does not drop late video frames worked well on
more powerful systems, and is still available with the UxPlay option
"`-vsync no`"; this method is adapted to "live streaming", and may be
better when Using UxPlay as a second monitor for a Mac computer, for
example, while the new default timestamp-based method is best for
watching a video, to keep lip movements and voices synchronized.
(Without use of timestamps, video will eventually lag behind audio if it
cannot be decoded fast enough: hardware-accelerated video-decoding
helped to prevent this previously when timestamps were not being used.)
- In Audio-only mode the "sync=false" option is also the default, but
if you want to keep the audio playing on the server synchronized
with the video on the client, use the `-async` option. (An example
might be if you want to follow the Apple Music lyrics on the client
while listening to superior sound on the UxPlay server). This delays
the video on the client to match audio on the server, so leads to a
- In Audio-only mode the GStreamer "sync=false" mode (not using
timestamps) is still the default, but if you want to keep the audio
playing on the server synchronized with the video showing on the
client, use the `-async` timestamp-based option. (An example might
be if you want to follow the Apple Music lyrics on the client while
listening to superior sound on the UxPlay server). This delays the
video on the client to match audio on the server, so leads to a
slight delay before a pause or track-change initiated on the client
takes effect on the audio played by the server.
@@ -411,8 +427,8 @@ value advances it.)
- you may find video is improved by the setting -fps 60 that allows
some video to be played at 60 frames per second. (You can see what
framerate is actually streaming by using -vs fpsdisplaysink, and/or
-FPSdata.) When using this, you probably should use the -vsync
option.
-FPSdata.) When using this, you should use the default
timestamp-based synchronization option `-vsync`.
- Since UxPlay-1.54, you can display the accompanying "Cover Art" from
sources like Apple Music in Audio-Only (ALAC) mode: run
@@ -433,9 +449,9 @@ options.
### **Special instructions for Raspberry Pi (tested on R Pi 4 model B 8GB and R Pi 3 model B+)**:
- If you use the software-only (h264) video-decoding UxPlay option
`-avdec`, you also need option `-vsync`to keep audio and video
synchronized (`-vsync` is a new feature; before it was introduced,
software decoding on the Pi was not viable.)
`-avdec`, it now works better that earlier, with the new default
timestamp-based synchronization to keep audio and video
synchronized.
- For best performance, the Raspberry Pi needs the GStreamer
Video4linux2 plugin to use its Broadcom GPU hardware for decoding
@@ -453,8 +469,8 @@ For use of the GPU, use raspi-config "Performance Options" (on Raspberry
Pi OS, use a similar tool on other distributions) to allocate sufficient
memory for the GPU (on R. Pi 3 model B+, the maximum (256MB) is
suggested). Even with GPU video decoding, some frames may be dropped by
the lower-power 3 B+, so the -vsync option (introduced in UxPlay-1.63)
that uses timestamps to synchronize audio and video is needed.
the lower-power 3 B+ to keep audio and video synchronized using
timestamps.
- The plugin in the latest GStreamer-1.22 release works well, but
older releases of GStreamer will not work unless patched with
@@ -464,18 +480,18 @@ that uses timestamps to synchronize audio and video is needed.
instructions in the UxPlay
Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches).
The basic uxplay options for R Pi are `uxplay -vsync [-vs <videosink>]`.
The choice `<videosink>` = `glimagesink` is sometimes useful. On a
system without X11 (like R Pi OS Lite) with framebuffer video, use
The basic uxplay options for R Pi are `uxplay [-vs <videosink>]`. The
choice `<videosink>` = `glimagesink` is sometimes useful. On a system
without X11 (like R Pi OS Lite) with framebuffer video, use
`<videosink>` = `kmssink`. With the Wayland video compositor, use
`<videosink>` = `waylandsink`. When using the Video4Linux2 plugin to
access hardware video decoding, an option `-v4l2` may be useful: for
convenience, this also comes combined with various videosink options as
`-rpi`, `-rpigl` `-rpifb`, `-rpiwl`, respectively provided for X11, X11
with OpenGL, framebuffer, and Wayland systems. You may find that just
"`uxplay -vsync`", (*without* `-v4l2` or `-rpi*` options, which lets
GStreamer try to find the best video solution by itself) provides the
best results (the `-rpi*` options may be removed in a future release of
with OpenGL, framebuffer, and Wayland systems. **You may find that just
"`uxplay`", (*without* `-v4l2` or `-rpi*` options, which lets GStreamer
try to find the best video solution by itself) provides the best
results** (the `-rpi*` options may be removed in a future release of
UxPlay.)
- If you are using Raspberry Pi OS (Bullseye) with Video4Linux2 from
@@ -726,15 +742,19 @@ will also now be the name shown above the mirror display (X11) window.
**-nh** Do not append "@_hostname_" at the end of the AirPlay server
name.
**-vsync \[x\]** (In Mirror mode:) this option uses timestamps to
synchronize audio with video on the server, with an optional audio delay
in (decimal) milliseconds (*x* = "20.5" means 0.0205 seconds delay:
positive or negative delays less than a second are allowed.) It is
needed on low-power systems such as Raspberry Pi without hardware video
decoding. Standard desktop systems seem to work well without this
(streaming without use of timestamps was the only behavior prior to
UxPlay 1.63), but you may wish to use it there too. (It may become the
default in future releases.)
**-vsync \[x\]** (In Mirror mode:) this option (**now the default**)
uses timestamps to synchronize audio with video on the server, with an
optional audio delay in (decimal) milliseconds (*x* = "20.5" means
0.0205 seconds delay: positive or negative delays less than a second are
allowed.) It is needed on low-power systems such as Raspberry Pi without
hardware video decoding.
**-vsync no** (In Mirror mode:) this switches off timestamp-based
audio-video synchronization, restoring the default behavior prior to
UxPlay-1.64. Standard desktop systems seem to work well without use of
timestamps: this mode is appropriate for "live streaming" such as using
UxPlay as a second monitor for a mac computer, or monitoring a webcam;
with it, no video frames are dropped.
**-async \[x\]** (In Audio-Only (ALAC) mode:) this option uses
timestamps to synchronize audio on the server with video on the client,
@@ -748,6 +768,10 @@ using the `-al` audio latency setting to change the latency (default
0.25 secs) that the server reports to the client, but at present
changing this does not seem to have any effect*.
**-async no**. This is the still the default behavior in Audio-only
mode, but this option may be useful as a command-line option to switch
of a `-async` option set in a "uxplayrc" configuration file.
**-s wxh** (e.g. -s 1920x1080 , which is the default ) sets the display
resolution (width and height, in pixels). (This may be a request made to
the AirPlay client, and perhaps will not be the final resolution you
@@ -1080,8 +1104,8 @@ also needs the bcm2835-codec kernel module that is not in the standard
Linux kernel (it is available in Raspberry Pi OS, Ubuntu and Manjaro).
- **If this kernel module is not available in your Raspberry Pi
operating system, or if GStreamer \< 1.22 is not patched, use
options `-avdec -vsync` for software h264-decoding.**
operating system, or if GStreamer \< 1.22 is not patched, use option
`-avdec` for software h264-decoding.**
Sometimes "autovideosink" may select the OpenGL renderer "glimagesink"
which may not work correctly on your system. Try the options "-vs
@@ -1241,6 +1265,11 @@ The "features" code and other settings are set in
# Changelog
1.64 2023-04-23 Timestamp-based synchronization of audio and video is
now the default in Mirror mode. (Use "-vsync no" to restore previous
behavior.) A configuration file can now be used for startup options.
Also some internal cleanups and a minor bugfix that fixes #192.
1.63 2023-02-12 Reworked audio-video synchronization, with new options
-vsync (for Mirror mode) and -async (for Audio-Only mode, to sync with
client video). Option -vsync makes software h264 decoding of streamed

1
renderers/CMakeLists.txt
View File

@@ -19,6 +19,7 @@ if ( X11_FOUND )
if ( GST120_FOUND )
message( "-- ZOOMFIX will NOT be applied as Gstreamer version is >= 1.20" )
else()
message( "-- Failure to find Gstreamer >= 1.20 is NOT an error!" )
message( "-- ZOOMFIX will be applied as Gstreamer version is < 1.20" )
add_definitions( -DZOOM_WINDOW_NAME_FIX )
endif()

38
uxplay.1
View File

@@ -1,23 +1,27 @@
.TH UXPLAY "1" "February 2023" "1.63" "User Commands"
.TH UXPLAY "1" "April 2023" "1.64" "User Commands"
.SH NAME
uxplay \- start AirPlay server
.SH SYNOPSIS
.B uxplay
[\fI\,-n name\/\fR] [\fI\,-s wxh\/\fR] [\fI\,-p \/\fR[\fI\,n\/\fR]] [more \fI OPTIONS \/\fR ...]
.SH DESCRIPTION
UxPlay 1.63: An open\-source AirPlay mirroring (+ audio streaming) server.
UxPlay 1.64: An open\-source AirPlay mirroring (+ audio streaming) server:
.SH OPTIONS
.TP
.B
\fB\-n\fR name Specify the network name of the AirPlay server
.TP
\fB\-nh\fR Do \fBNOT\fR append "@\fIhostname\fR" at end of the AirPlay server name
\fB\-nh\fR Do \fBNOT\fR append "@\fIhostname\fR" at end of AirPlay server name
.TP
\fB\-vsync\fR Mirror mode: sync audio to video (default: stream w/o sync)
\fB\-vsync\fI[x]\fR Mirror mode: sync audio to video using timestamps (default)
.IP
\fIx\fR is optional audio delay: millisecs, decimal, can be neg.
.TP
\fB\-vsync\fI[x]\fR \fIx\fR is optional audio delay in millisecs, can be neg., decimal.
\fB\-vsync\fR no Switch off audio/(server)video timestamp synchronization.
.TP
\fB\-async\fR[\fIx\fR] Audio-Only mode: sync audio to client video (default: no sync).
\fB\-async\fR[\fIx\fR] Audio-Only mode: sync audio to client video (default: no).
.TP
\fB\-async\fR no Switch off audio/(client)video timestamp synchronization.
.TP
\fB\-s\fR wxh[@r]Set display resolution [refresh_rate] default 1920x1080[@60]
.TP
@@ -121,3 +125,25 @@ UxPlay 1.63: An open\-source AirPlay mirroring (+ audio streaming) server.
\fB\-v\fR Displays version information
.TP
\fB\-h\fR Displays help information
.SH
FILES
.TP
Options in one of $UXPLAYRC, or ~/.uxplayrc, or ~/.config/uxplayrc
.TP
are applied first (command-line options may modify them). uxplayrc format:
.TP
one option per line,\fI no\fR initial "-"; lines beginning with "#" ignored.
.SH
AUTHORS
.TP
Various, see website or distribution.
.SH
COPYRIGHT
.TP
Various, see website or distribution. License: GPL v3+: GNU GPL version 3 or later.
.TP
(some parts LGPL v.2.1 and MIT).
.SH
SEE ALSO
.TP
Website: <https://github.com/FDH2/UxPlay>

27
uxplay.cpp
View File

@@ -59,7 +59,7 @@
#include "renderers/video_renderer.h"
#include "renderers/audio_renderer.h"
#define VERSION "1.63"
#define VERSION "1.64"
#define SECOND_IN_USECS 1000000
#define SECOND_IN_NSECS 1000000000UL
@@ -75,7 +75,7 @@ static dnssd_t *dnssd = NULL;
static raop_t *raop = NULL;
static logger_t *render_logger = NULL;
static bool audio_sync = false;
static bool video_sync = false;
static bool video_sync = true;
static int64_t audio_delay_alac = 0;
static int64_t audio_delay_aac = 0;
static bool relaunch_video = false;
@@ -398,17 +398,17 @@ static std::string random_mac () {
}
static void print_info (char *name) {
printf("UxPlay %s: An open-source AirPlay mirroring server based on RPiPlay\n", VERSION);
printf("=========== Website: https://github.com/FDH2/UxPlay =============\n");
printf("Usage: %s [-n name] [-s wxh] [-p [n]]\n", name);
printf("UxPlay %s: An open-source AirPlay mirroring server.\n", VERSION);
printf("=========== Website: https://github.com/FDH2/UxPlay ==========\n");
printf("Usage: %s [-n name] [-s wxh] [-p [n]] [(other options)]\n", name);
printf("Options:\n");
printf("-n name Specify the network name of the AirPlay server\n");
printf("-nh Do not add \"@hostname\" at the end of the AirPlay server name\n");
printf("-vsync [x]Mirror mode: sync audio to video (default: stream w/o sync)\n");
printf(" x is optional audio delay in millisecs, can be neg., decimal\n");
printf("-vsync no Switch off vsync audio/(server)video timestamp synchronization \n");
printf("-async [x]Audio-Only mode: sync audio to client video (default: no sync)\n");
printf("-async no Switch off async audio/(client)video timestamp synchronization\n");
printf("-nh Do not add \"@hostname\" at the end of AirPlay server name\n");
printf("-vsync [x]Mirror mode: sync audio to video using timestamps (default)\n");
printf(" x is optional audio delay: millisecs, decimal, can be neg.\n");
printf("-vsync no Switch off audio/(server)video timestamp synchronization \n");
printf("-async [x]Audio-Only mode: sync audio to client video (default: no)\n");
printf("-async no Switch off audio/(client)video timestamp synchronization\n");
printf("-s wxh[@r]Set display resolution [refresh_rate] default 1920x1080[@60]\n");
printf("-o Set display \"overscanned\" mode on (not usually needed)\n");
printf("-fs Full-screen (only works with X11, Wayland and VAAPI)\n");
@@ -429,7 +429,7 @@ static void print_info (char *name) {
printf(" gtksink,waylandsink,osximagesink,kmssink,d3d11videosink etc.\n");
printf("-vs 0 Streamed audio only, with no video display window\n");
printf("-v4l2 Use Video4Linux2 for GPU hardware h264 decoding\n");
printf("-bt709 A workaround (bt709 color) that may be needed with -rpi\n");
printf("-bt709 A workaround (bt709 color) sometimes needed on RPi\n");
printf("-rpi Same as \"-v4l2\" (for RPi=Raspberry Pi).\n");
printf("-rpigl Same as \"-rpi -vs glimagesink\" for RPi.\n");
printf("-rpifb Same as \"-rpi -vs kmssink\" for RPi using framebuffer.\n");
@@ -459,6 +459,9 @@ static void print_info (char *name) {
printf("-d Enable debug logging\n");
printf("-v Displays version information\n");
printf("-h Displays this help\n");
printf("Startup options in $UXPLAYRC, ~/.uxplayrc, or ~/.config/uxplayrc are\n");
printf("applied first (command-line options may modify them): format is one \n");
printf("option per line, no initial \"-\"; lines starting with \"#\" are ignored.\n");
}
bool option_has_value(const int i, const int argc, std::string option, const char *next_arg) {