morgan/UxPlay
1
0
Fork 0
mirror of https://github.com/morgan9e/UxPlay synced 2026-04-14 16:24:29 +09:00
Code Issues Packages Projects Releases Wiki Activity

README update for v1.73.5

Browse Source
This commit is contained in:
F. Duncanh
2026-03-19 03:49:29 -04:00
parent 6d0ff39bf7
commit 3d71c13136
3 changed files with 291 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

171
README.txt
View File

@@ -2,7 +2,7 @@
### **Now developed at the GitHub site <https://github.com/FDH2/UxPlay> (where ALL user issues should be posted, and latest versions can be found).**
- **NEW in v1.73** (January 2026):
- **NEW in v1.73, up to v1.73.5** (March 2026):
- Some YouTube app HLS videos now offer alternative language tracks
(generated by AI dubbing). Language choices will be made in order of
@@ -17,22 +17,22 @@
- Support for **service discovery using a Bluetooth LE "beacon"** for
both Linux/\*BSD and Windows (as an alternative to
Bonjour/Rendezvous DNS-SD service discovery). **This can be used on
networks that do not allow the user to run a DNS_SD service.** The
user must run a Bluetooth LE "beacon", (a USB 4.0 or later "dongle"
can be used). The beacon is managed by a Python3 script
`uxplay-beacon.py`: four implementations of Bleutooth LE advertising
are available as loadable modules: BlueZ for Linux only, winrt for
Windows only, BleuIO for the BlueIO usb-serial dongle (which has its
own BlueTooth-LE stack, independent of that of the host system) that
runs on all systems including macOS and \*BSD), and a low-level HCI
module (Linux and BSD only) that access the Host Contoller Interface
(but users need enhanced privileges to use this). The beacon runs
independently of UxPlay: while UxPlay is running, it regularly
broadcasts a Bluetooth LE ("Low Energy") 46 byte legacy-type
advertisement informing nearby iOS/macOS devices of the local IPv4
network address of the UxPlay server, and which TCP port to contact
UxPlay on. Instructions are [given
Bonjour/Rendezvous DNS-SD service discovery) was introduced in v1.73
and improved in 1.73.5. This can be used on networks that do not
allow the user to run a DNS_SD service.\*\* The user must run a
Bluetooth LE "beacon", (Bluetooth 4.0 or later is needed, a cheap
USD "dongle" will do.). The beacon is managed by a Python \>= 3.6
script `uxplay-beacon.py`. Loadable Python modules provide
appropriate Bluetooth LE support for Linux, Windows, and FreeBSD;
*macOS is only supported by the BleuIO USB dongle which uniquely has
its own Bluetooth LE stack based on a Renesas SoC, and is seen by
the host as a serial modem (this can be used on all the operating
systems supported by Uxplay, including other BSD variants).* The
beacon runs independently of UxPlay. While UxPlay is running, the
beacon regularly broadcasts a Bluetooth LE ("Low Energy") 46 byte
legacy-type advertisement informing nearby iOS/macOS devices of the
local IPv4 network address of the UxPlay server, and which TCP port
to contact UxPlay on. Instructions are [given
below](#bluetooth-le-beacon-setup).
- option `-vrtp <rest-of-pipeline>` bypasses rendering by UxPlay, and
@@ -1595,35 +1595,61 @@ this to see even more of the GStreamer inner workings.
The python\>=3.6 script for running a Bluetooth LE Service Discovery
beacon is uxplay-beacon.py. It provides four possible Bluetooth LE
implementations (loaded as modules): one for Linux systems with D-Bus,
one for Windows, and one for the [BleuIO (or BleuIO Pro) USB
dongle](https://www.bleuio.com) with its own on-board Bluetooth-LE Stack
that does not use the host operating system Bluetooth (the Host sees the
device as a USB serial modem). This is needed for macOS where the
operating system does not allow users to send Bluetooth-LE
advertisements of the type we require. If a BleuIO dongle is available,
the bleuio version of the python script can be used on many operating
systems including macOS, Windows and Linux, and perhaps \*BSD (not
tested): it requires python library `python3-pyserial` to be installed.
implementations (loaded as modules):
A fourth implementation (module HCI) for Linux or FreeBSD (maybe other
BSD's too?) requires elevated permissions to access the Host Controller
Interface. These are granted by adding users to a new group "hciusers"
that are give permission to call "`sudo -n hcitool/hciconfig/hccontrol`"
without entering a password: this can be configured by the system
admistrator using visudo, but has security implications.
- **BlueZ** for Linux systems with D-Bus;
On Linux, Bluetooth support (using the offical Linux Bluetooth stack
BlueZ) must be installed (on Debian-based systems:
- **winrt** for Windows;
- **BleuIO** for the [BleuIO (or BleuIO Pro) USB
dongle](https://www.bleuio.com) with its own on-board Bluetooth-LE
Stack that does not use the host operating system Bluetooth (the
host sees the device as a USB serial modem). This is needed for
macOS where the native operating system Bluetooth stack does not
allow users to send Bluetooth-LE advertising data of the
"manufacturer-specific" type `AdvData=0xFF`. If a BleuIO dongle
(currently costs about USD25) is available, the BleuIO version of
the python script can be used on many operating systems including
macOS, Windows, Linux, FreeBSD, and probably other BSD variants (not
tested): it requires python library `python3-pyserial` to be
installed. On Linux, users must be members of group `dialout` or
sometimes `uucp` (`dialer` on FreeBSD).
- **HCI** for Linux without D-Bus (uses utiities `hcitool` and
`hciconfig`) or FreeBSD (uses `hccontrol`) and requires elevated
privileges to access the Host Controller Interface. These privileges
can be granted by adding users to a new group "hciusers" that are
given permission to call "`sudo -n hci*`" (`hci*` = hcitool,
hciconfig or hccontrol) without entering a password: this can be
configured by the system administrator using `visudo` (*security
implications should be considered*). Use visudo to create a file
`hciusers` in `/etc/sudoers.d/` (Linux) or
`/usr/local/etc/sudoers.d` (FreeBSD), containing the line
"`%hciusers ALL=(ALL) NOPASSWD: <hcitools>`" (where `<hcitools>` is
replaced by "`/usr/bin/hcitool, /usr/bin/hciconfig`" (Linux) or
"`/usr/sbin/hccontrol`" (FreeBSD). In addition, FreeBSD's
`hccontrol` needs a patch to allow generic LE Advertising Data to be
input. We have submitted it to FreeBSD as a Pull Request, and you
can find it on the \[UxPlay Wiki\]
(https://github.com/FDH2/UxPlay/wiki/hccontrol-patch-for-FreeBSD-15.0)
On Linux, Bluetooth support (using the official Linux Bluetooth stack
BlueZ, and D-Bus) must be installed (on Debian-based systems:
`sudo apt install bluez bluez-tools`; recent Ubuntu releases provide
bluez as a snap package). In addition to standard Python3 libraries, you
may need to install the gi, dbus, and psutil Python libraries used by
uxplay-beacon.py. On Debian-based systems:
bluez as a snap package). BlueZ tools 'hcitool' and 'hciconfig' (needed
if you use the HCI module on Linux) are declared "deprecated" by the
BlueZ developers: some Linux distributions have removed them from the
default BleuZ packages, into "extra" packages with names like
"bluez-deprecated".
In addition to standard Python3 libraries, you may need to install the
gi, dbus, and psutil Python libraries used by uxplay-beacon.py. On
Debian-based systems:
sudo apt install python3-gi python3-dbus python3-psutil
If a python3-gi package is not found, install the python3-gobject
package which provides it.
If a python3-gi package is available in your Linux distribution, install
the python3-gobject package which provides it.
For Windows support in the MSYS2 UCRT64 environment, use pacman -S to
install `mingw-w64-ucrt-x86_64-python`, `*-python-gobject`,
@@ -1640,12 +1666,12 @@ installations (such as the one provided in MSYS2) should be
pip install .... --break-system-packages
The option `--break-system-packages` was required to make users hesitate
before adding packages not provided by the "external management": *this
is unnecessarily scary, as in the case of the winrt packages, no
breakage will occur*.
The option `--break-system-packages` was added as a requirement to make
users hesitate before adding packages not provided by the "external
management": *this is unnecessarily scary, as in the case of the winrt
packages, no breakage can occur*.
If uxplay will be run with option "`uxplay -ble`" (so it writes data for
UxPlay must be run with option "`uxplay -ble`" (so it writes data for
the Bluetooth beacon in the default BLE data file `~/.uxplay.ble`), just
run `uxplay-beacon.py` in a separate terminal. The python script will
start Bluetooth LE Service-Discovery advertising when it detects that
@@ -1665,6 +1691,11 @@ Get help with `man uxplay-beacon` or `uxplay-beacon.py --help`.
Options are
- `<module>` where "module" is BleuIO or HCI (no intital `--`) .
Without this option, the default module used will be **BlueZ**
(Linux), **winrt** (Windows), **BleuIO** (all other operating
systems).
- `--file <config file>` read beacon options from `<config file>`
instead of `~/.uxplay.beacon`.
@@ -1679,8 +1710,8 @@ Options are
This also requires that uxplay is run with option
"`uxplay -ble <BLE data file>`".
The BlueZ/Dbus version has three more options not offered by the Windows
version (the Windows operating system chooses their values):
These are the only options accepted by the **winrt** module on Windows.
The other modules accept
- `--advmin x`, `--advmax y`. These controls the interval between BLE
advertisement broadcasts. This interval is in the range \[x, y\],
@@ -1691,6 +1722,11 @@ version (the Windows operating system chooses their values):
are advmin = advmax = 100. The advertisement is broadcast on all
three Bluetooth LE advertising channels: 37,38,39.
On a Windows system, the values of these paramaters are set by the
operating system, and cannot be set by users.
The **BlueZ** module (Linux) also accepts
- `--index x` (default x = 0, x \>= 0). This can be used by the DBus
to distinguish between multiple simultaneous instances of
uxplay-beacon.py that are running to support multiple instances of
@@ -1699,13 +1735,22 @@ version (the Windows operating system chooses their values):
*Note: running multiple beacons simultaneously on the same host has
not been tested, and this option might not be useful or needed.*
While the native macOS and \*BSD Bluetooth stacks do not allow
unpriviledged users to send "manufacturer-specific" advertisements like
the uxplay service discovery announcement, this can be achieved using
the BleuIO USB device: the BleuIO module for uxplay-beacon.py is
installed with UxPlay in all operating systems, including macos and
\*BSD, while the BlueZ and winrt modules are only installed on Linux and
Windows, respectively.
The **BleuIO** and **HCI** modules accept
- `--device x` which allows overiding automatically-made choices of
serial ports (**BleuIO**) or hci device nodes (**HCI**). This is
probably only useful if the host system has multiple devices that
could be used.
The native macOS Bluetooth stack has no documented way for users to send
"manufacturer-specific" Bluetooth LE advertisements (such that sent for
AirPlay Service Discovery), and the only support of uxplay-beacon.py on
macOS uses a BleuIO USB serial device. However macOS provides a
low-level utility BlueTool (found at `/usr/sbin/bluetool`) that can send
HCI commands, so possibly could be used to adapt the python3 **HCI**
module to support macOS as well (*working implementations welcome!*).
**The recommended and working method on macOS is to use a BleuIO
dongle.**
If you wish to test Bluetooth LE Service Discovery on Linux/\*BSD, you
can disable DNS_SD Service discovery by the avahi-daemon with
@@ -1721,15 +1766,9 @@ Management**: press "Windows + R" to open the Run dialog, run
`services.msc`, and click on **Bonjour Service** in the alphabetic list.
This will show links for it to be stopped and restarted.
For more information, see the [wiki
page](https://github.com/FDH2/UxPlay/wiki/Bluetooth_LE_beacon). This
page also explains how to setup a BLE beacon for UxPlay on Linux by
direct accesss to the Bluetooth stack using `hcitool` to send low-level
HCI commands, with root privileges. This can also be done on FreeBSD
using `hccontrol`, and on macOS using `bluetool`. **The recommended way
to set up Bluetooth LE Service Discovery on macOS or \*BSD is to acquire
a BleuIO USB device, which is supported by uxplay-beacon.py without root
privileges**.
For more information on Bluetooth LE support, including HCI commands,
see the [wiki
page](https://github.com/FDH2/UxPlay/wiki/Bluetooth_LE_beacon).
- **Note that Bluetooth LE AirPlay Service Discovery only supports
broadcast of IPv4 addresses**.
@@ -1769,7 +1808,11 @@ start, stop, status. You might need to edit the avahi-daemon.conf file
"disable-publishing" is **not** a selected option). 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;
see [here](https://gist.github.com/reidransom/6033227).)
see [here](https://gist.github.com/reidransom/6033227), or [section
32.8.1 of the FreeBSD
Handbook](https://docs.freebsd.org/en/books/handbook/network-servers/#_configuring_and_starting_avahi))
Note that avahi service is not needed if you instead use a Bluetooth LE
beacon (see [above](#bluetooth-le-beacon-setup)) for Service-Discovery.
- **uxplay starts, but either stalls or stops after "Initialized
server socket(s)" appears (*without the server name showing on the