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 edit (minor)

Browse Source
This commit is contained in:
F. Duncanh
2024-01-29 12:55:51 -05:00
parent 2190125736
commit 7238c0743f
3 changed files with 122 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
README.md
View File

@@ -377,17 +377,14 @@ are opened: **if a firewall is active, also open UDP port 5353 (for mDNS queries
needed by Avahi**. See [Troubleshooting](#troubleshooting) below for
help with this or other problems.
* Since v 1.67, the UxPlay option "`-pin`" allows clients to "pair" with the UxPlay server
the first time they connect to it, by entering
a 4-digit pin code that is displayed on the UxPlay terminal. (This is optional, but sometimes required if the client is a
corporately-owned and -managed device with MDM Mobile Device Management.) Pairing occurs just once, is currently only
recorded by the client unless the -reg option is used, and persists until the
UxPlay public key is changed. By default (since v1.68) the public key is now generated using the "Device ID", which is either the server's
hardware MAC address, or
can be set with the -m option (most conveniently using the startup option file). (Storage of a more securely-generated
persistent key as an OpenSSL "pem" file is still available with the -key option). For use of uxplay in a more public environment, a
list of previously-registered clients can (since v1.68) be optionally-maintained using the -reg option: without this
option, returning clients claiming to be registered are just trusted and not checked.
* Unlike an Apple TV, the UxPlay server
does not by default require clients to initially "pair" with it using a pin code
displayed by the server (after which the client "trusts" the server, and does not
need to repeat this). Since v1.67, Uxplay offers such "pin-authentication" as an option:
see "`-pin`" and "``-reg``" in [Usage](#usage) for details, if you wish to use
it. _Some clients
with MDM (Mobile Device Management, often present on employer-owned devices) are required to use pin-authentication: UxPlay will
provide this even when running without the pin option._
* By default, UxPlay is locked to
its current client until that client drops the connection; since UxPlay-1.58, the option `-nohold` modifies this
@@ -399,7 +396,7 @@ a mechanism ( `-restrict`, ``-allow <id>``, ```-block <id>```) to control which
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
On low-decoding-power UxPlay hosts (such as Raspberry Pi Zero W or 3 B+ models) this will drop video frames that cannot be decoded in time
to play with the audio, making the video jerky, but still synchronized.
The older method which does not drop late video frames
@@ -417,8 +414,9 @@ if you want to follow the Apple Music lyrics on the client while listening to su
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.
AirPlay volume-control attenuates volume (gain) by up to -30dB: the range -30dB:0dB can be rescaled from _Low_:0, or _Low_:_High_, using the
option `-db` ("-db _Low_ " or "-db _Low_:_High_ "), _Low_ must be negative. Rescaling is linear in decibels. The option ```-taper``` provides a "tapered" AirPlay volume-control
AirPlay volume-control attenuates volume (gain) by up to -30dB: the decibel range -30:0 can be rescaled from _Low_:0, or _Low_:_High_, using the
option `-db` ("-db _Low_ " or "-db _Low_:_High_ "), _Low_ must be negative. Rescaling is linear in decibels. The
option ```-taper``` provides a "tapered" AirPlay volume-control
profile some users may prefer.
The -vsync and -async options
@@ -475,14 +473,14 @@ See [Usage](#usage) for more run-time options.
distributions that are known to supply it include Raspberry Pi OS, Ubuntu, and Manjaro-RPi4. Use
software decoding (option -avdec) if this module is not available.
* Uxplay uses the Video4Linux2 (v4l2) plugin from GStreamer-1.22 and later to access the GPU in models 3 and 4. This
* Uxplay uses the Video4Linux2 (v4l2) plugin from GStreamer-1.22 and later to access the GPU, if hardware H264 decoding is used. This
should happen automatically. The option -v4l2 can be used, but it is usually best to just let GStreamer find the
best video pipeline by itself.
* On older distributions (GStreamer < 1.22), the v4l2 plugin needs a patch: see
the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches). Legacy
Raspberry Pi OS (Bullseye) has a partially-patched GStreamer-1.18.4 which needs the uxplay option -bt709 (and don't use -v4l2); it
is still better to apply the full patch from the UzxPlay Wiki in this case.
is still better to apply the full patch from the UxPlay Wiki in this case.
* For "double-legacy" Raspberry Pi OS (Buster), there is no patch for GStreamer-1.14.
Instead, first build a complete newer GStreamer-1.18.6 from source
@@ -495,7 +493,7 @@ See [Usage](#usage) for more run-time options.
Even with GPU video decoding, some frames may be dropped by the lower-power models to keep audio and video synchronized
using timestamps. In Legacy Raspberry Pi OS (Bullseye), raspi-config "Performance Options" allows specifying how much memory
to allocate to the GPU, but this setting appears to be gone in Bookworm (it can also be set to e.g. 128GB with a line like "gpu_mem=128" in /boot/config.txt).
to allocate to the GPU, but this setting appears to be absent in Bookworm (but it can still be set to e.g. 128GB by adding a line "gpu_mem=128" in /boot/config.txt).
A Pi Zero 2 W (which has 512GB memory) worked well when tested in 32 bit Bullseye or Bookworm Lite
with 128GB allocated to the GPU (default seems to be 64GB).
@@ -600,7 +598,7 @@ After installing GStreamer, build and install uxplay: open a terminal and change
the (small) initial OpenGL mirror window size, but the window can be expanded using the mouse or trackpad.
In contrast, a window created with "-vs osxvideosink" is initially big, but has the wrong aspect ratio (stretched image);
in this case the aspect ratio changes when the window width is changed by dragging its side;
the option "-vs osxvideosink force-aspect-ratio=true" can be used to make the window have the
the option `-vs "osxvideosink force-aspect-ratio=true"` can be used to make the window have the
correct aspect ratio when it first opens.
## Building UxPlay on Microsoft Windows, using MSYS2 with the MinGW-64 compiler.
@@ -712,18 +710,17 @@ with "`#`" are treated as comments, and ignored. Command line options supersede
**-pin [nnnn]**: (since v1.67) use Apple-style (one-time) "pin" authentication when a new client connects for the first time: a four-digit pin code is
displayed on the terminal, and the client screen shows a login prompt for this to be entered. When "-pin" is used by itself, a new random
pin code is chosen for each authentication; if "-pin nnnn" (e.g., "-pin 3939") is used, this will set an unchanging fixed code.
Clients will not need to reauthenticate so long as the client and server public keys remain unchanged. (By default since v1.68, the server public key is
generated from the MAC address, which can be changed with the -m option; see the -key option for an alternative method of key
generation). _(Add a line "pin" in the UxPlay startup file if you wish the
UxPlay server to use the pin authentication protocol)._
pin code is chosen for each authentication; if "-pin nnnn" (e.g., "-pin 3939") is used, this will set an unchanging fixed code. Authentication adds the server to the client's list of
"trusted servers" and the client will not need to reauthenticate provided that the client and server public keys remain unchanged. (By default since v1.68, the server public key is
generated from the MAC address, which can be changed with the -m option; see the -key option for an alternative method of key
generation). _(Add a line "pin" in the UxPlay startup file if you wish the UxPlay server to use the pin authentication protocol)._
**-reg [_filename_]**: (since v1.68). This option maintains a list of previously-pin-registered clients in $HOME/.uxplay.register (or optionally, in _filename_).
Without this option, returning clients claiming to be already pin-registered are trusted and not checked. (This option may be useful if UxPlay is used
in a more public environment, to record client details; the register is text, one line per client, with client's public
**-reg [_filename_]**: (since v1.68). If "-pin" is used, this option
maintains a register of pin-authenticated "trusted clients" in $HOME/.uxplay.register (or optionally, in _filename_).
Without this option, returning clients that skip pin-authentication are trusted and not checked. This option may be useful if UxPlay is used
in a more public environment, to record client details; the register is text, one line per client, with client's public
key (base-64 format), Device ID, and Device name; commenting out (with "#") or deleting a line deregisters the
corresponding client.) _(Add a line "reg" in the startup file if you wish to use this feature.)_
corresponding client (see options -restrict, -block, -allow for more ways to control client access). _(Add a line "reg" in the startup file if you wish to use this feature.)_
**-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
@@ -814,7 +811,7 @@ which will not work if a firewall is running.
"..." allows some parameters to be included with the videosink name.
For example, **fullscreen** mode is supported by the vaapisink plugin, and is
obtained using ``-vs "vaapisink fullscreen=true"``; this also works with ``waylandsink``.
The syntax of such options is specific to a given plugin, and some choices of videosink
The syntax of such options is specific to a given plugin (see GStreamer documentation), and some choices of videosink
might not work on your system.
**-vs 0** suppresses display of streamed video. In mirror mode, the client's screen
@@ -840,9 +837,10 @@ which will not work if a firewall is running.
**-as _audiosink_** chooses the GStreamer audiosink, instead of letting
autoaudiosink pick it for you. Some audiosink choices are: pulsesink, alsasink, pipewiresink,
osssink, oss4sink, jackaudiosink, osxaudiosink (for macOS), wasapisink, directsoundsink (for Windows). Using quotes
"..." might allow some parameters to be included with the audiosink name.
(Some choices of audiosink might not work on your system.)
osssink, oss4sink, jackaudiosink, osxaudiosink (for macOS), wasapisink, directsoundsink (for Windows).
Using quotes "..." might allow some optional parameters (e.g. `-as "alsasink device=..."` to specify a non-default output device).
The syntax of such options is specific to a given plugin (see GStreamer documentation), and some choices of audiosink
might not work on your system.
**-as 0** (or just **-a**) suppresses playing of streamed audio, but displays streamed video.