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 updates for 1.67

Browse Source
This commit is contained in:
F. Duncanh
2023-12-01 18:55:57 -05:00
parent 6dfcb12e98
commit e9da98f428
4 changed files with 223 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
README.md
View File

@@ -1,7 +1,10 @@
# UxPlay 1.67: 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).
### Now developed at the GitHub site [https://github.com/FDH2/UxPlay](https://github.com/FDH2/UxPlay) (where ALL user issues should be posted, and latest versions can be found).
* _**NEW in v1.67**: support for one-time Apple-style "pin" code client authentication ("client-server
pairing") when the option "-pin" is used._
## Highlights:
* GPLv3, open source.
@@ -19,18 +22,18 @@
to select different hardware-appropriate output "videosinks" and
"audiosinks", and a fully-user-configurable video streaming pipeline).
* Support for server behind a firewall.
* Raspberry Pi support **both with and without hardware video decoding** by the Broadcom GPU. _Tested on Raspberry Pi 5, Pi 4 Model B and Pi 3 model B+._
* Raspberry Pi support **both with and without hardware video decoding** by the
Broadcom GPU. _Tested on Raspberry Pi Models 3B+, 4B, and 5._
* Support for running on Microsoft Windows (builds with the MinGW-64 compiler in the
unix-like MSYS2 environment).
* _NEW in v1.67: support for one-time Apple-style "pin" code client authentication ("client-server pairing") when the option "-pin" is used._
## Packaging status (Linux and \*BSD distributions)
[![Current Packaging status](https://repology.org/badge/vertical-allrepos/uxplay.svg)](https://repology.org/project/uxplay/versions).
* Install uxplay on Debian-based Linux systems with "`sudo apt install uxplay`"; on FreeBSD with "``sudo pkg install uxplay``". Also
available on Arch-based systems through AUR. Since v. 1.66, uxplay is now also packaged in RPM format by Fedora 38 ("``sudo dnf install uxplay``").
* Install uxplay on Debian-based Linux systems with "`sudo apt install uxplay`"; on FreeBSD
with "``sudo pkg install uxplay``". Also available on Arch-based systems through AUR. Since v. 1.66,
uxplay is now also packaged in RPM format by Fedora 38 ("``sudo dnf install uxplay``").
* For other RPM-based distributions which have not yet packaged UxPlay, a RPM "specfile" **uxplay.spec** is now provided with recent
[releases](https://github.com/FDH2/UxPlay/releases) (see their "Assets"), and can also be found in the UxPlay source top directory.
@@ -73,10 +76,11 @@ main [UxPlay site](https://github.com/FDH2/UxPlay)).
UxPlay is tested on a number of systems, including (among others) Debian (10 "Buster", 11 "Bullseye", 12 "Bookworm"),
Ubuntu (20.04 LTS, 22.04 LTS, 23.04 (also Ubuntu derivatives Linux Mint, Pop!\_OS), Red Hat and clones (Fedora 38,
Rocky Linux 9.2), openSUSE Leap 15.5, Mageia 9, OpenMandriva "ROME", PCLinuxOS, Arch Linux, Manjaro, and should run on any Linux system.
Also tested on macOS 13.3 (Intel and M2), FreeBSD 13.2, Windows 10 and 11 (64 bit).
Also tested on macOS Catalina and Ventura (Intel) and Sonoma (M2), FreeBSD 14.0, 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.04 LTS and 23.04, Manjaro RPi4 23.02,
and (without hardware video decoding) on openSUSE 15.5. Also tested on Raspberry Pi 3 model B+.
On Raspberry Pi 4 model B, it is tested on Raspberry Pi OS (Bullseye and Bookworm) (32- and 64-bit),
Ubuntu 22.04 LTS and 23.04, Manjaro RPi4 23.02, and (without hardware video decoding) on openSUSE 15.5.
Also tested on Raspberry Pi 3 model B+ and the new model 5.
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
@@ -369,11 +373,19 @@ 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 only
recorded in the client, and persists unless the
UxPlay public key (stored in $HOME/.uxplay.pem, or elsewhere if option `-key <filename>` is used) is moved or deleted, after
which a new key is generated. (Non-Apple clients might not implement the persistence feature.)
* By default, UxPlay is locked to
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. UxPlay 1.66 introduces
a mechanism ( `-restrict`, ``-allow <id>``, ```-block <id>```) to control which clients are allowed to connect, using their
"deviceID" (which appears to be immutable).
"deviceID" (which in Apple devices appears to be immutable).
* 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
@@ -471,17 +483,16 @@ 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`", (_without_ ``-v4l2`` or ```-rpi*``` options, which lets GStreamer
plugin to access hardware video decoding, an option `-v4l2` may be useful.
**You may find that just "`uxplay`", (_without_ the ``-v4l2`` option, 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 former`-rpi*` options were equivalent to `-v4l2` or ``-v4l2`` plus one of
the '-vs' options, and were removed in UxPlay v1.67 as they do not apply to R Pi model 5.)
* 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.
Also don't use options `-v4l2` and ``-rpi*`` with it, as they
cause a crash if the client screen is rotated. (These issues do not occur when the latest GStreamer-1.18.4
Also don't use option `-v4l2` with it, as this
causes a crash if the client screen is rotated. (These issues do not occur when the latest GStreamer-1.18.4
patch from the UxPlay Wiki has been applied.)
* Tip: to start UxPlay on a remote host (such as a Raspberry Pi) using ssh:
@@ -689,13 +700,13 @@ with "`#`" are treated as comments, and ignored. Command line options supersede
**-nh** Do not append "@_hostname_" at the end of the AirPlay server name.
**-pin [nnnn]**: 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 randon
pin code is chosen for each authentication; "-pin nnnn" (e.g., "-pin 3939") will set an unchanging fixed code. Persistence of client
authentication requires that the public key of the UxPlay server remains the same each time it is started: this is achieved by storing the key
in a file (which by default is $HOME/.uxplay.pem, but which can be changed with the `"-key <filename>"` option) which (if it does not exist) is
created the first time the -pin option is used, and is subsequently read each time the server starts. So long as this file is not deleted or moved,
clients will not have to authenticate again after their first successful authentication. _(Add a "pin" entry in the UxPlay startup file if you wish the
**-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.
To retain client authentication after UxPlay restarts, at the first use of "-pin", the server public key is written to file (default: $HOME/.uxplay.pem; can
be changed with option `-key <filename>`),
and read back in at subsequent UxPlay startups. As long as this file is not deleted or moved, a
client will not have to re-authenticate after an initial authentication. _(Add a "pin" entry in the UxPlay startup file if you wish the
UxPlay server to use this protocol)._
**-vsync [x]** (In Mirror mode:) this option (**now the default**) uses timestamps to synchronize audio with video on the server,
@@ -790,16 +801,13 @@ which will not work if a firewall is running.
use of an uncommon (but permitted) "full-range color" variant of the bt709 color standard for digital TV.
This is no longer needed by GStreamer-1.20.4 and backports from it.
**-rpi** Equivalent to "-v4l2 ". Use for "Desktop" Raspberry Pi systems with X11.
**-rpi** Equivalent to "-v4l2 " (Not valid for Raspberry Pi model 5, and removed in UxPlay 1.67)
**-rpigl** Equivalent to "-rpi -vs glimagesink". Sometimes better for "Desktop" Raspberry Pi systems with X11.
**-rpigl** Equivalent to "-rpi -vs glimagesink". (Removed since UxPlay 1.67)
**-rpifb** Equivalent to "-rpi -vs kmssink" (use for Raspberry Pi systems
using the framebuffer, like RPi OS Bullseye Lite).
**-rpifb** Equivalent to "-rpi -vs kmssink" (Removed since UxPlay 1.67)
**-rpiwl** Equivalent to "-rpi -vs waylandsink", for Raspberry
Pi "Desktop" systems using the Wayland video compositor (use for
Ubuntu 21.10 for Raspberry Pi 4B).
**-rpiwl** Equivalent to "-rpi -vs waylandsink". (Removed since UxPlay 1.67)
**-as _audiosink_** chooses the GStreamer audiosink, instead of letting
autoaudiosink pick it for you. Some audiosink choices are: pulsesink, alsasink, pipewiresink,
@@ -872,10 +880,13 @@ which will not work if a firewall is running.
**-r {R|L}** 90 degree Right (clockwise) or Left (counter-clockwise)
rotations; these image transforms are carried out after any **-f** transforms.
**-m** generates a random MAC address to use instead of the true hardware MAC
number of the computer's network card. (Different server_name, MAC
**-m [mac]** changes the MAC address (Device ID) used by UxPlay (default is to use
the true hardware MAC address reported by the host computer's network card).
(Different server_name, MAC
addresses, and network ports are needed for each running uxplay if you
attempt to run two instances of uxplay on the same computer.)
attempt to run more than one instance of uxplay on the same computer.)
If [mac] (in form xx:xx:xx:xx:xx:xx, 6 hex octets) is not given, a random
MAC address is generated.
If UxPlay fails to find the true MAC address of a network card, (more
specifically, the MAC address used by the first active network interface detected)
a random MAC address will be used even if option **-m** was not specified.
@@ -886,8 +897,6 @@ which will not work if a firewall is running.
as a line "`key filename`" (no initial "-"), where ``filename`` is a full path. The filename may be enclosed
in quotes (`"...."`), (and must be, if the filename has any blank spaces).
**-t _timeout_** [This option was removed in UxPlay v.1.61.]
**-vdmp** Dumps h264 video to file videodump.h264. -vdmp n dumps not more than n NAL units to
videodump.x.h264; x= 1,2,... increases each time a SPS/PPS NAL unit arrives. To change the name
_videodump_, use -vdmp [n] _filename_.
@@ -1111,7 +1120,7 @@ connection setup, without a 5 second delay) by disabling "Supports Legacy Pairin
on DNS-SD Service Discovery. Most clients will then not attempt the setup of a "shared secret key" when pairing, which is used by AppleTV for simultaneous
handling of multiple clients (UxPlay only supports one client at a time).
**This change is now well-tested, but in case it causes any protocol failures, UxPlay can be reverted to the previous behavior by uncommenting the previous "FEATURES_1" setting
(and commenting out the new one) in lib/dnssdint.h, and then rebuilding UxPlay.**
(and commenting out the new one) in lib/dnssdint.h, and then rebuilding UxPlay.** ("Pairing" is re-enabled when the new Apple-style one-time "pin" authentication is activated by running UxPlay with the "-pin" option introduced in UxPlay 1.67.)
Protocol failure should not happen for iOS 9.3 or later clients. However, if a client
@@ -1128,13 +1137,16 @@ Note that for DNS-SD Service Discovery, Uxplay declares itself to be an AppleTV3
sourceVersion 220.68; this can also be changed in global.h.
UxPlay also works if it declares itself as an AppleTV6,2 with
sourceVersion 380.20.1 (an AppleTV 4K 1st gen, introduced 2017, running
tvOS 12.2.1), so it does not seem to matter what UxPlay claims to be.
tvOS 12.2.1), so it does not seem to matter what version UxPlay claims to be.
# Changelog
1.67 2023-11-29 Add support for Apple-style one-time pin authentication of clients with option "-pin":
(SRP6a authentication protocol) and public key persistence. Detection of (so far)
unsupported H265 video when requesting high resolution over wired ethernet.
1.67 2023-11-30 Add support for Apple-style one-time pin authentication of clients with option "-pin":
(uses SRP6a authentication protocol and public key persistence). Detection with error message
of (currently) unsupported H265 video when requesting high resolution over wired ethernet.
Removed rpi* options (which are not valid with new Raspberry Pi model 5, and can be replaced
by combinations of other options). Added optional argument "mac" to "-m" option, to
specify a replacement MAC address/Device ID. Update llhttp to v. 9.1.3.
1.66 2023-09-05 Fix IPV6 support. Add option to restrict clients to those on a list of allowed deviceIDs,
or to block connections from clients on a list of blocked deviceIDs. Fix for #207 from