forked from antimof/UxPlay
-
Notifications
You must be signed in to change notification settings - Fork 88
/
Copy pathREADME.txt
1974 lines (1645 loc) · 101 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# UxPlay 1.71: 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, and latest versions can be found).**
- ***NEW in v1.71**: Support for (YouTube) HLS (HTTP Live Streaming)
video with the new "-hls" option.* **Only streaming from the YouTube
iOS app (in \"m3u8\" protocol) is currently supported**: (streaming
using the AirPlay icon in a browser window is **not** yet
supported).Click on the airplay icon in the YouTube app to stream
video. (You may need to wait until advertisements have finished or
been skipped before clicking the YouTube airplay icon.) **Please
report any issues with this new feature of UxPlay**. *The default
video player for HLS is GStreamer playbin v3: use "-hls 2" to revert
to playbin v2 if some videos fail to play*.
## Highlights:
- GPLv3, open source.
- Originally supported only AirPlay Mirror protocol, now has added
support for AirPlay Audio-only (Apple Lossless ALAC) streaming from
current iOS/iPadOS clients. **Now with support for Airplay HLS
video-streaming (currently only YouTube video).**
- macOS computers (2011 or later, both Intel and "Apple Silicon" M1/M2
systems) can act either as AirPlay clients, or as the server running
UxPlay. Using AirPlay, UxPlay can emulate a second display for macOS
clients.
- Support for older iOS clients (such as 32-bit iPad 2nd gen., iPod
Touch 5th gen. and iPhone 4S, when upgraded to iOS 9.3.5, or later
64-bit devices), plus a Windows AirPlay-client emulator, AirMyPC.
- Uses GStreamer plugins for audio and video rendering (with options
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 Zero 2 W, 3
Model B+, 4 Model B, and 5.*
- Support for running on Microsoft Windows (builds with the MinGW-64
compiler in the unix-like MSYS2 environment).
Note: AirPlay2 multi-room audio streaming is not supported: use
[shairport-sync](https://github.com/mikebrady/shairport-sync) for that.
## Packaging status (Linux and \*BSD distributions)
[](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`").
- 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.
See the section on using this specfile for [building an installable
RPM package](#building-an-installable-rpm-package).
After installation:
- (On Linux and \*BSD): if a firewall is active on the server hosting
UxPlay, make sure the default network port (UDP 5353) for
mDNS/DNS-SD queries is open (see [Troubleshooting](#troubleshooting)
below for more details); also open three UDP and three TCP ports for
Uxplay, and use the "uxplay -p `<n>`{=html}" option (see
"`man uxplay`" or "`uxplay -h`").
- Even if you install your distribution's pre-compiled uxplay binary
package, you may need to read the instructions below for [running
UxPlay](#running-uxplay) to see which of your distribution's
**GStreamer plugin packages** you should also install.
- For Audio-only mode (Apple Music, etc.) best quality is obtained
with the option "uxplay -async", but there is then a 2 second
latency imposed by iOS.
- Add any UxPlay options you want to use as defaults to a startup file
`~/.uxplayrc` (see "`man uxplay`" or "`uxplay -h`" for format and
other possible locations). In particular, if your system uses
PipeWire audio or Wayland video systems, you may wish to add "as
pipewiresink" or "vs waylandsink" as defaults to the file. *(Output
from terminal commands "ps waux \| grep pulse" or "pactl info" will
contain "pipewire" if your Linux/BSD system uses it).*
- On Raspberry Pi: models using hardware h264 video decoding by the
Broadcom GPU (models 4B and earlier) may require the uxplay option
-bt709. If you use Ubuntu 22.10 or earlier, GStreamer must be
[patched](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
to use hardware video decoding by the Broadcom GPU (also recommended
but optional for Raspberry Pi OS (Bullseye): the patched GStreamer
does not need option " -bt709\`". The need for -bt709 when hardware
video decoding is used seems to have reappeared starting with
GStreamer-1.22.
To (easily) compile the latest UxPlay from source, see the section
[Getting UxPlay](#getting-uxplay).
# Detailed description of UxPlay
This project is a GPLv3 open source unix AirPlay2 Mirror server for
Linux, macOS, and \*BSD. It was initially developed by
[antimof](http://github.com/antimof/Uxplay) using code from
OpenMAX-based [RPiPlay](https://github.com/FD-/RPiPlay), which in turn
derives from [AirplayServer](https://github.com/KqsMea8/AirplayServer),
[shairplay](https://github.com/juhovh/shairplay), and
[playfair](https://github.com/EstebanKubata/playfair). (The antimof site
is no longer involved in 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 "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 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 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 Zero 2 W, 3 model B+, and now 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 of a host running Linux, macOS, or other unix (and
now also Microsoft Windows). UxPlay supports Apple's AirPlay2 protocol
using "Legacy Protocol", but some features are missing. (Details of what
is publicly known about Apple's AirPlay 2 protocol can be found
[here](https://openairplay.github.io/airplay-spec/),
[here](https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol)
and [here](https://emanuelecozzi.net/docs/airplay2); see also
[pyatv](https://pyatv.dev/documentation/protocols) which could be a
resource for adding modern protocols.) While there is no guarantee that
future iOS releases will keep supporting "Legacy Protocol", iOS 17
continues support.
The UxPlay server and its client must be on the same local area network,
on which a **Bonjour/Zeroconf mDNS/DNS-SD server** is also running (only
DNS-SD "Service Discovery" service is strictly 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
[Avahi](https://www.avahi.org), through the avahi-daemon service, and is
included in most Linux distributions (this service can also be provided
by macOS, iOS or Windows servers).
Connections to the UxPlay server by iOS/MacOS clients can be initiated
both in **AirPlay Mirror** mode (which streams lossily-compressed AAC
audio while mirroring the client screen, or in the alternative **AirPlay
Audio** mode which streams Apple Lossless (ALAC) audio without screen
mirroring. In **Audio** mode, metadata is displayed in the uxplay
terminal; if UxPlay option `-ca <name>` is used, the accompanying cover
art is also output to a periodically-updated file `<name>`, and can be
viewed with a (reloading) graphics viewer of your choice. *Switching
between* **Mirror** *and* **Audio** *modes during an active connection
is possible: in* **Mirror** *mode, stop mirroring (or close the mirror
window) and start an* **Audio** *mode connection, switch back by
initiating a* **Mirror** *mode connection; cover-art display
stops/restarts as you leave/re-enter* **Audio** *mode.*
- **Note that Apple video-DRM (as found in "Apple TV app" content on
the client) cannot be decrypted by UxPlay, and the Apple TV app
cannot be watched using UxPlay's AirPlay Mirror mode (only the
unprotected audio will be streamed, in AAC format).**
- **With the new "-hls" option, UxPlay now also supports non-Mirror
AirPlay video streaming (where the client controls a web server on
the AirPlay server that directly receives HLS content to avoid it
being decoded and re-encoded by the client). This currently only
supports streaming of YouTube videos. Without the -hls option, using
the icon for AirPlay video in apps such as the YouTube app will only
send audio (in lossless ALAC format) without the accompanying
video.**
### Possibility for using hardware-accelerated h264/h265 video-decoding, if available.
UxPlay uses [GStreamer](https://gstreamer.freedesktop.org) "plugins" for
rendering audio and video. This means that video and audio are supported
"out of the box", using a choice of plugins. AirPlay streams video in
h264 format: gstreamer decoding is plugin agnostic, and uses accelerated
GPU hardware h264 decoders if available; if not, software decoding is
used.
- **VAAPI for Intel and AMD integrated graphics, NVIDIA with "Nouveau"
open-source driver**
With an Intel or AMD GPU, hardware decoding with the open-source
VAAPI gstreamer plugin is preferable. The open-source "Nouveau"
drivers for NVIDIA graphics are also in principle supported: see
[here](https://nouveau.freedesktop.org/VideoAcceleration.html), but
this requires VAAPI to be supplemented with firmware extracted from
the proprietary NVIDIA drivers.
- **NVIDIA with proprietary drivers**
The `nvh264dec` plugin (included in gstreamer1.0-plugins-bad since
GStreamer-1.18.0) can be used for accelerated video decoding on the
NVIDIA GPU after NVIDIA's CUDA driver `libcuda.so` is installed. For
GStreamer-1.16.3 or earlier, the plugin is called `nvdec`, and must
be [built by the
user](https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins).
- **Video4Linux2 support for h264 hardware decoding on Raspberry Pi
(Pi 4B and older)**
Raspberry Pi (RPi) computers (tested on Pi 4 Model B) can now run
UxPlay using software video decoding, but hardware-accelerated
h264/h265 decoding by firmware in the Pi's Broadcom 2835 GPU is
prefered. UxPlay accesses this using the GStreamer-1.22 Video4Linux2
(v4l2) plugin; Uses the out-of-mainline Linux kernel module
bcm2835-codec maintained by Raspberry Pi, so far only included in
Raspberry Pi OS, and two other distributions (Ubuntu, Manjaro)
available with Raspberry Pi Imager. *(For GStreamer \< 1.22, see the
[UxPlay
Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches))*.
Pi model 5 has no support for hardware H264 decoding, as its CPU is
powerful enough for satisfactory software H264 decoding
- **Support for h265 (HEVC) hardware decoding on Raspberry Pi (Pi 4
model B and Pi 5)**
These Raspberry Pi models have a dedicated HEVC decoding block (not
the GPU), with a driver "rpivid" which is not yet in the mainline
Linux kernel (but is planned to be there in future). Unfortunately
it produces decoded video in a non-standard pixel format (NC30 or
"SAND") which will not be supported by GStreamer until the driver is
in the mainline kernel; without this support, UxPlay support for
HEVC hardware decoding on Raspberry Pi will not work.
### Note to packagers:
UxPlay's GPLv3 license does not have an added "GPL exception" explicitly
allowing it to be distributed in compiled form when linked to OpenSSL
versions **prior to v. 3.0.0** (older versions of OpenSSL have a license
clause incompatible with the GPL unless OpenSSL can be regarded as a
"System Library", which it is in \*BSD). Many Linux distributions treat
OpenSSL as a "System Library", but some (e.g. Debian) do not: in this
case, the issue is solved by linking with OpenSSL-3.0.0 or later.
# Getting UxPlay
Either download and unzip
[UxPlay-master.zip](https://github.com/FDH2/UxPlay/archive/refs/heads/master.zip),
or (if git is installed): "git clone https://github.com/FDH2/UxPlay".
You can also download a recent or earlier version listed in
[Releases](https://github.com/FDH2/UxPlay/releases).
- A recent UxPlay can also be found on the original [antimof
site](https://github.com/antimof/UxPlay); that original project is
inactive, but is usually kept current or almost-current with the
[active UxPlay github site](https://github.com/FDH2/UxPlay) (thank
you antimof!).
## Building UxPlay on Linux (or \*BSD):
### Debian-based systems:
(Adapt these instructions for non-Debian-based Linuxes or \*BSD; for
macOS, see specific instruction below). See
[Troubleshooting](#troubleshooting) below for help with any
difficulties.
You need a C/C++ compiler (e.g. g++) with the standard development
libraries installed. Debian-based systems provide a package
"build-essential" for use in compiling software. You also need
pkg-config: if it is not found by "`which pkg-config`", install
pkg-config or its work-alike replacement pkgconf. Also make sure that
cmake\>=3.10 is installed: "`sudo apt install cmake`" (add
`build-essential` and `pkg-config` (or `pkgconf`) to this if needed).
Make sure that your distribution provides OpenSSL 1.1.1 or later, and
libplist 2.0 or later. (This means Debian 10 "Buster" based systems
(e.g, Ubuntu 18.04) or newer; on Debian 10 systems "libplist" is an
older version, you need "libplist3".) If it does not, you may need to
build and install these from source (see instructions at the end of this
README).
If you have a non-standard OpenSSL installation, you may need to set the
environment variable OPENSSL_ROOT_DIR (*e.g.* ,
"`export OPENSSL_ROOT_DIR=/usr/local/lib64`" if that is where it is
installed). Similarly, for non-standard (or multiple) GStreamer
installations, set the environment variable GSTREAMER_ROOT_DIR to the
directory that contains the ".../gstreamer-1.0/" directory of the
gstreamer installation that UxPlay should use (if this is *e.g.*
"\~/my_gstreamer/lib/gstreamer-1.0/", set this location with
"`export GSTREAMER_ROOT_DIR=$HOME/my_gstreamer/lib`").
- Most users will use the GStreamer supplied by their distribution,
but a few (in particular users of Raspberry Pi OS Lite Legacy
(Buster) on a Raspberry Pi model 4B who wish to stay on that
unsupported Legacy OS for compatibility with other apps) should
instead build a newer Gstreamer from source following [these
instructions](https://github.com/FDH2/UxPlay/wiki/Building-latest-GStreamer-from-source-on-distributions-with-older-GStreamer-(e.g.-Raspberry-Pi-OS-).)
. **Do this *before* building UxPlay**.
In a terminal window, change directories to the source directory of the
downloaded source code ("UxPlay-\*", "\*" = "master" or the release tag
for zipfile downloads, "UxPlay" for "git clone" downloads), then follow
the instructions below:
**Note:** By default UxPlay will be built with optimization for the
computer it is built on; when this is not the case, as when you are
packaging for a distribution, use the cmake option
`-DNO_MARCH_NATIVE=ON`.
If you use X11 Windows on Linux or \*BSD, and wish to toggle in/out of
fullscreen mode with a keypress (F11 or Alt_L+Enter) UxPlay needs to be
built with a dependence on X11. Starting with UxPlay-1.59, this will be
done by default **IF** the X11 development libraries are installed and
detected. Install these with "`sudo apt install libx11-dev`". If
GStreamer \< 1.20 is detected, a fix needed by screen-sharing apps
(*e.g.*, Zoom) will also be made.
- If X11 development libraries are present, but you wish to build
UxPlay *without* any X11 dependence, use the cmake option
`-DNO_X11_DEPS=ON`.
1. `sudo apt install libssl-dev libplist-dev`". (*unless you need to
build OpenSSL and libplist from source*).
2. `sudo apt install libavahi-compat-libdnssd-dev`
3. `sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev`.
(\**Skip if you built Gstreamer from source*)
4. `cmake .` (*For a cleaner build, which is useful if you modify the
source, replace this by* "`mkdir build; cd build; cmake ..`": *you
can then delete the contents of the `build` directory if needed,
without affecting the source.*) Also add any cmake "`-D`" options
here as needed (e.g, `-DNO_X11_DEPS=ON` or `-DNO_MARCH_NATIVE=ON`).
5. `make`
6. `sudo make install` (you can afterwards uninstall with
`sudo make uninstall` in the same directory in which this was run).
This installs the executable file "`uxplay`" to `/usr/local/bin`, (and
installs a manpage to somewhere standard like
`/usr/local/share/man/man1` and README files to somewhere like
`/usr/local/share/doc/uxplay`). (If "man uxplay" fails, check if
\$MANPATH is set: if so, the path to the manpage (usually
/usr/local/share/man/) needs to be added to \$MANPATH .) The uxplay
executable can also be found in the build directory after the build
process, if you wish to test before installing (in which case the
GStreamer plugins must first be installed).
### Building on non-Debian Linux and \*BSD
\*\*For those with RPM-based distributions, a RPM spec file uxplay.spec
is also available: see [Building an installable rpm
package](#building-an-installable-rpm-package).
- **Red Hat, or clones like CentOS (now continued as Rocky Linux or
Alma Linux):** (sudo dnf install, or sudo yum install) openssl-devel
libplist-devel avahi-compat-libdns_sd-devel gstreamer1-devel
gstreamer1-plugins-base-devel (+libX11-devel for fullscreen X11)
*(some of these may be in the "CodeReady" add-on repository, called
"PowerTools" by clones)*
- **Mageia, PCLinuxOS, OpenMandriva:** Same as Red Hat, except for
name changes: (Mageia) "gstreamer1.0-devel",
"gstreamer-plugins-base1.0-devel"; (OpenMandriva)
"libopenssl-devel", "gstreamer-devel",
"libgst-plugins-base1.0-devel". PCLinuxOS: same as Mageia, but uses
synaptic (or apt) as its package manager.
- **openSUSE:** (sudo zypper install) libopenssl-3-devel (formerly
libopenssl-devel) libplist-2_0-devel (formerly libplist-devel)
avahi-compat-mDNSResponder-devel gstreamer-devel
gstreamer-plugins-base-devel (+ libX11-devel for fullscreen X11).
- **Arch Linux** (*Also available as a package in AUR*): (sudo pacman
-Syu) openssl libplist avahi gst-plugins-base.
- **FreeBSD:** (sudo pkg install) libplist gstreamer1. Either
avahi-libdns or mDNSResponder must also be installed to provide the
dns_sd library. OpenSSL is already installed as a System Library.
#### Building an installable RPM package
First-time RPM builders should first install the rpm-build and
rpmdevtools packages, then create the rpmbuild tree with
"`rpmdev-setuptree`". Then download and copy uxplay.spec into
`~/rpmbuild/SPECS`. In that directory, run
"`rpmdev-spectool -g -R uxplay.spec`" to download the corresponding
source file `uxplay-*.tar.gz` into `~/rpmbuild/SOURCES`
("rpmdev-spectool" may also be just called "spectool"); then run
"`rpmbuild -ba uxplay.spec`" (you will need to install any required
dependencies this reports). This should create the uxplay RPM package in
a subdirectory of `~/rpmbuild/RPMS`. (**uxplay.spec** is tested on
Fedora 38, Rocky Linux 9.2, openSUSE Leap 15.5, Mageia 9, OpenMandriva,
PCLinuxOS; it can be easily modified to include dependency lists for
other RPM-based distributions.)
## Running UxPlay
### Installing plugins (Debian-based Linux distributions, including Ubuntu and Raspberry Pi OS) (*skip if you built a complete GStreamer from source*)
Next install the GStreamer plugins that are needed with
`sudo apt install gstreamer1.0-<plugin>`. Values of `<plugin>` required
are:
1. "**plugins-base**"
2. "**libav**" (for sound),
3. "**plugins-good**" (for v4l2 hardware h264 decoding)
4. "**plugins-bad**" (for h264 decoding).
**Debian-based distributions split some of the plugin packages into
smaller pieces:** some that may also be needed include "**gl**" for
OpenGL support (this provides the "-vs glimagesink" videosink, which can
be very useful in many systems (including Raspberry Pi), and should
always be used when using h264/h265 decoding by a NVIDIA GPU),
"**gtk3**" (which provides the "-vs gtksink" videosink), and "**x**" for
X11 support, although these may already be installed; "**vaapi**" is
needed for hardware-accelerated h264 video decoding by Intel or AMD
graphics (but not for use with NVIDIA using proprietary drivers). If
sound is not working, "**alsa**"","**pulseaudio**", or "**pipewire**"
plugins may need to be installed, depending on how your audio is set up.
- Also install "**gstreamer1.0-tools**" to get the utility
gst-inspect-1.0 for examining the GStreamer installation.
### Installing plugins (Non-Debian-based Linux or \*BSD) (*skip if you built a complete GStreamer from source*)
In some cases, because of patent issues, the libav plugin feature
**avdec_aac** needed for decoding AAC audio in mirror mode is not
provided in the official distribution: get it from community
repositories for those distributions.
- **Red Hat, or clones like CentOS (now continued as Rocky Linux or
Alma Linux):** Install gstreamer1-libav gstreamer1-plugins-bad-free
(+ gstreamer1-vaapi for Intel/AMD graphics). In recent Fedora,
gstreamer1-libav is renamed gstreamer1-plugin-libav. **To get
avdec_aac, install packages from
[rpmfusion.org](https://rpmfusion.org)**: (get ffmpeg-libs from
rpmfusion; on RHEL or clones, but not recent Fedora, also get
gstreamer1-libav from there).
- **Mageia, PCLinuxOS, OpenMandriva:** Install gstreamer1.0-libav
gstreamer1.0-plugins-bad (+ gstreamer1.0-vaapi for Intel/AMD
graphics). **On Mageia, to get avdec_aac, install ffmpeg from the
"tainted" repository**, (which also provides a more complete
gstreamer1.0-plugins-bad).
- **openSUSE:** Install gstreamer-plugins-libav gstreamer-plugins-bad
(+ gstreamer-plugins-vaapi for Intel/AMD graphics). **To get
avdec_aac, install libav\* packages for openSUSE from
[Packman](https://ftp.gwdg.de/pub/linux/misc/packman/suse/)
"Essentials"**; recommendation: after adding the Packman repository,
use the option in YaST Software management to switch all system
packages for multimedia to Packman).
- **Arch Linux** Install gst-plugins-good gst-plugins-bad gst-libav (+
gstreamer-vaapi for Intel/AMD graphics).
- **FreeBSD:** Install gstreamer1-libav, gstreamer1-plugins,
gstreamer1-plugins-\* (\* = core, good, bad, x, gtk, gl, vulkan,
pulse, v4l2, ...), (+ gstreamer1-vaapi for Intel/AMD 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 specify
fullscreen mode with the `-fs` option, or 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 iOS client's drop-down "Screen Mirroring" panel, check
that your DNS-SD server (usually avahi-daemon) is running: do this in a
terminal window with `systemctl status avahi-daemon`. If this shows the
avahi-daemon is not running, control it with
`sudo systemctl [start,stop,enable,disable] avahi-daemon` (on
non-systemd systems, such as \*BSD, use
`sudo service avahi-daemon [status, start, stop, restart, ...]`). If
UxPlay is seen, but the client fails to connect when it is selected,
there may be a firewall on the server that prevents UxPlay from
receiving client connection requests unless some network ports 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.
- 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 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 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 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 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 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 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.
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. Note that GStreamer's audio
format will "clip" any audio gain above +20db, so keep *High* below that
level. The option `-taper` provides a "tapered" AirPlay volume-control
profile some users may prefer.
The -vsync and -async options also allow an optional positive (or
negative) audio-delay adjustment in *milliseconds* for fine-tuning :
`-vsync 20.5` 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 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 is "feh": run
"`feh -R 1 <name>`" in the foreground; terminate feh and then Uxplay
with "`ctrl-C fg ctrl-C`".
By default, GStreamer uses an algorithm to search for the best
"videosink" (GStreamer's term for a graphics driver to display images)
to use. You can overide this with the uxplay option `-vs <videosink>`.
Which videosinks are available depends on your operating system and
graphics hardware: use
"`gst-inspect-1.0 | grep sink | grep -e video -e Video -e image`" to see
what is available. Some possibilites on Linux/\*BSD are:
- **glimagesink** (OpenGL), **waylandsink**
- **xvimagesink**, **ximagesink** (X11)
- **kmssink**, **fbdevsink** (console graphics without X11)
- **vaapisink** (for Intel/AMD hardware-accelerated graphics); for
NVIDIA hardware graphics (with CUDA) use **glimagesink** combined
with "`-vd nvh264dec`" (or "nvh264sldec", a new variant which will
become "nvh264dec" in GStreamer-1.24).
- If the server is "headless" (no attached monitor, renders audio
only) use `-vs 0`.
Note that videosink options can set using quoted arguments to -vs:
*e.g.*, `-vs "xvimagesink display=:0"`: ximagesink and xvimagesink allow
an X11 display name to be specified, and waylandsink has a similar
option. Videosink options ("properties") can be found in their GStreamer
description pages,such as
https://gstreamer.freedesktop.org/documentation/xvimagesink .
GStreamer also searches for the best "audiosink"; override its choice
with `-as <audiosink>`. Choices on Linux include pulsesink, alsasink,
pipewiresink, oss4sink; see what is available with
`gst-inspect-1.0 | grep sink | grep -e audio -e Audio`.
**One common problem involves GStreamer attempting to use
incorrectly-configured or absent accelerated hardware h264 video
decoding (e.g., VAAPI). Try "`uxplay -avdec`" to force software video
decoding; if this works you can then try to fix accelerated hardware
video decoding if you need it, or just uninstall the GStreamer vaapi
plugin.**
See [Usage](#usage) for more run-time options.
### **Special instructions for Raspberry Pi (tested on Raspberry Pi Zero 2 W, 3 Model B+, 4 Model B, and 5 only)**:
- For Framebuffer video (for Raspberry Pi OS "Lite" and other non-X11
distributions) use the KMS videosink "-vs kmssink" (the DirectFB
framebuffer videosink "dfbvideosink" is broken on the Pi, and
segfaults). *In this case you should explicitly use the "-vs
kmssink" option, as without it, autovideosink does not find the
correct videosink.*
- Raspberry Pi 5 does not provide hardware H264 decoding (and does not
need it).
- Pi Zero 2 W, 3 Model B+ and 4 Model B should use hardware H264
decoding by the Broadcom GPU, but it requires an out-of-mainstream
kernel module bcm2835_codec maintained in the [Raspberry Pi kernel
tree](https://github.com/raspberrypi/linux); 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, 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 UxPlay
Wiki in this case.
- **It appears that when hardware h264 video decoding is used, the
option -bt709 became needed again in GStreamer-1.22 and later.**
- 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 using [these
instructions](https://github.com/FDH2/UxPlay/wiki/Building-latest-GStreamer-from-source-on-distributions-with-older-GStreamer-(e.g.-Raspberry-Pi-OS-).)
before building UxPlay.
- Raspberry Pi 3 Model B+ running a 32 bit OS can also access the GPU
with the GStreamer OMX plugin (use option "`-vd omxh264dec`"), but
this is broken by Pi 4 Model B firmware. OMX support was removed
from Raspberry Pi OS (Bullseye), but is present in Buster.
- **H265 (4K)** video is potentially supported by hardware decoding on
Raspberry Pi 5 models, as well as on Raspberry Pi 4 model B, using a
dedicated HEVC decoding block, but the "rpivid" kernel driver for
this is not yet supported by GStreamer (this driver decodes video
into a non-standard format that cannot be supported by GStreamer
until the driver is in the mainline Linux kernel). Raspberry Pi
provides a version of ffmpeg that can use that format, but at
present UxPlay cannot use this. The best solution would be for the
driver to be "upstreamed" to the kernel, allowing GStreamer support.
(Software HEVC decoding works, but does not seem to give
satisfactory results on the Pi).
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 absent in Bookworm (but it can
still be set to e.g. 128MB by adding a line "gpu_mem=128" in
/boot/config.txt). A Pi Zero 2 W (which has 512MB memory) worked well
when tested in 32 bit Bullseye or Bookworm Lite with 128MB allocated to
the GPU (default seems to be 64MB).
The basic uxplay options for R Pi are `uxplay [-vs <videosink>]`. The
choice `<videosink>` = `glimagesink` is sometimes useful. With the
Wayland video compositor, use `<videosink>` = `waylandsink`. With
framebuffer video, use `<videosink>` = `kmssink`.
- Tip: to start UxPlay on a remote host (such as a Raspberry Pi) using
ssh:
```{=html}
<!-- -->
```
ssh user@remote_host
export DISPLAY=:0
nohup uxplay [options] > FILE &
Sound and video will play on the remote host; "nohup" will keep uxplay
running if the ssh session is closed. Terminal output is saved to FILE
(which can be /dev/null to discard it)
## Building UxPlay on macOS: **(Intel X86_64 and "Apple Silicon" M1/M2 Macs)**
*Note: A native AirPlay Server feature is included in macOS 12 Monterey,
but is restricted to recent hardware. UxPlay can run on older macOS
systems that will not be able to run Monterey, or can run Monterey but
not AirPlay.*
These instructions for macOS assume that the Xcode command-line
developer tools are installed (if Xcode is installed, open the Terminal,
type "sudo xcode-select --install" and accept the conditions).
It is also assumed that CMake \>= 3.13 is installed: this can be done
with package managers [MacPorts](http://www.macports.org)
(`sudo port install cmake`), [Homebrew](http://brew.sh)
(`brew install cmake`), or by a download from
<https://cmake.org/download/>. Also install `git` if you will use it to
fetch UxPlay.
Next install libplist and openssl-3.x. Note that static versions of
these libraries will be used in the macOS builds, so they can be
uninstalled after building uxplay, if you wish.
- If you use Homebrew: `brew install libplist openssl@3`
- if you use MacPorts: `sudo port install libplist-devel openssl3`
Otherwise, build libplist and openssl from source: see instructions near
the end of this README; requires development tools (autoconf, automake,
libtool, *etc.*) to be installed.
Next get the latest macOS release of GStreamer-1.0.
**Using "Official" GStreamer (Recommended for both MacPorts and Homebrew
users)**: install the GStreamer release for macOS from
<https://gstreamer.freedesktop.org/download/>. (This release contains
its own pkg-config, so you don't have to install one.) Install both the
gstreamer-1.0 and gstreamer-1.0-devel packages. After downloading,
Shift-Click on them to install (they install to
/Library/FrameWorks/GStreamer.framework). Homebrew or MacPorts users
should **not** install (or should uninstall) the GStreamer supplied by
their package manager, if they use the "official" release.
- Since GStreamer v1.22, the "Official" (gstreamer.freedesktop.org)
macOS binaries require a wrapper "gst_macos_main" around the actual
main program (uxplay). This should have been applied during the
UxPlay compilation process, and the initial UxPlay terminal message
should confirm it is being used. (UxPlay can also be built using
"Official" GStreamer v.1.20.7 binaries, which work without the
wrapper.)
**Using Homebrew's GStreamer**: pkg-config is needed: ("brew install
pkg-config gstreamer"). This causes a large number of extra packages to
be installed by Homebrew as dependencies. The [Homebrew gstreamer
installation](https://formulae.brew.sh/formula/gstreamer#default) has
recently been reworked into a single "formula" named `gstreamer`, which
now works without needing GST_PLUGIN_PATH to be set in the enviroment.
Homebrew installs gstreamer to `HOMEBREW_PREFIX/lib/gstreamer-1.0` where
by default `HOMEBREW_PREFIX/*` is `/opt/homebrew/*` on Apple Silicon
Macs, and `/usr/local/*` on Intel Macs; do not put any extra
non-Homebrew plugins (that you build yourself) there, and instead set
GST_PLUGIN_PATH to point to their location (Homebrew does not supply a
complete GStreamer, but seems to have everything needed for UxPlay).
**New: the UxPlay build script will now also detect Homebrew
installations in non-standard locations indicated by the environment
variable `$HOMEBREW_PREFIX`.**
**Using GStreamer installed from MacPorts**: this is **not**
recommended, as currently the MacPorts GStreamer is old (v1.16.2),
unmaintained, and built to use X11:
- Instead [build gstreamer
yourself](https://github.com/FDH2/UxPlay/wiki/Building-GStreamer-from-Source-on-macOS-with-MacPorts)
if you use MacPorts and do not want to use the "Official" Gstreamer
binaries.
*(If you really wish to use the MacPorts GStreamer-1.16.2, install
pkgconf ("sudo port install pkgconf"), then "sudo port install
gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good
gstreamer1-gst-plugins-bad gstreamer1-gst-libav". For X11 support on
macOS, compile UxPlay using a special cmake option `-DUSE_X11=ON`, and
run it from an XQuartz terminal with -vs ximagesink; older non-retina
macs require a lower resolution when using X11: `uxplay -s 800x600`.)*
After installing GStreamer, build and install uxplay: open a terminal
and change into the UxPlay source directory ("UxPlay-master" for zipfile
downloads, "UxPlay" for "git clone" downloads) and build/install with
"cmake . ; make ; sudo make install" (same as for Linux).
- Running UxPlay while checking for GStreamer warnings (do this with
"export GST_DEBUG=2" before runnng UxPlay) reveals that with the
default (since UxPlay 1.64) use of timestamps for video
synchonization, many video frames are being dropped (only on macOS),
perhaps due to another error (about videometa) that shows up in the
GStreamer warnings. **Recommendation: use the new UxPlay "no
timestamp" option "`-vsync no`"** (you can add a line "vsync no" in
the uxplayrc configuration file).
- On macOS with this installation of GStreamer, the only videosinks
available seem to be glimagesink (default choice made by
autovideosink) and osxvideosink. The window title does not show the
Airplay server name, but the window is visible to screen-sharing
apps (e.g., Zoom). The only available audiosink seems to be
osxaudiosink.
- The option -nc is always used, whether or not it is selected. This
is a workaround for a problem with GStreamer videosinks on macOS: if
the GStreamer pipeline is destroyed while the mirror window is still
open, a segfault occurs.
- In the case of glimagesink, the resolution settings "-s wxh" do not
affect 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 correct aspect ratio when it first opens.
## Building UxPlay on Microsoft Windows, using MSYS2 with the MinGW-64 compiler.
- tested on Windows 10 and 11, 64-bit.
1. Download and install **Bonjour SDK for Windows v3.0**. You can
download the SDK without any registration at
[softpedia.com](https://www.softpedia.com/get/Programming/SDK-DDK/Bonjour-SDK.shtml),
or get it from the official Apple site
[https://developer.apple.com/download](https://developer.apple.com/download/all/?q=Bonjour%20SDK%20for%20Windows)
(Apple makes you register as a developer to access it from their
site). This should install the Bonjour SDK as
`C:\Program Files\Bonjour SDK`.
2. (This is for 64-bit Windows; a build for 32-bit Windows should be
possible, but is not tested.) The unix-like MSYS2 build environment
will be used: download and install MSYS2 from the official site
[https://www.msys2.org/](https://www.msys2.org). Accept the default
installation location `C:\mysys64`.
3. [MSYS2 packages](https://packages.msys2.org/package/) are installed
with a variant of the "pacman" package manager used by Arch Linux.
Open a "MSYS2 MINGW64" terminal from the MSYS2 tab in the Windows
Start menu, and update the new MSYS2 installation with "pacman
-Syu". Then install the **MinGW-64** compiler and **cmake**
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc
The compiler with all required dependencies will be installed in the
msys64 directory, with default path `C:/msys64/mingw64`. Here we
will simply build UxPlay from the command line in the MSYS2
environment (this uses "`ninja`" in place of "`make`" for the build
system).
4. Download the latest UxPlay from github **(to use `git`, install it
with `pacman -S git`, then
"`git clone https://github.com/FDH2/UxPlay`")**, then install UxPlay
dependencies (openssl is already installed with MSYS2):
`pacman -S mingw-w64-x86_64-libplist mingw-w64-x86_64-gstreamer mingw-w64-x86_64-gst-plugins-base`
If you are trying a different Windows build system, MSVC versions of
GStreamer for Windows are available from the [official GStreamer
site](https://gstreamer.freedesktop.org/download/), but only the
MinGW 64-bit build on MSYS2 has been tested.
5. cd to the UxPlay source directory, then "`mkdir build`" and
"`cd build`". The build process assumes that the Bonjour SDK is
installed at `C:\Program Files\Bonjour SDK`. If it is somewhere
else, set the enviroment variable BONJOUR_SDK_HOME to point to its
location. Then build UxPlay with
`cmake ..`
`ninja`
6. Assuming no error in either of these, you will have built the uxplay
executable **uxplay.exe** in the current ("build") directory. The
"sudo make install" and "sudo make uninstall" features offered in
the other builds are not available on Windows; instead, the MSYS2
environment has `/mingw64/...` available, and you can install the
uxplay.exe executable in `C:/msys64/mingw64/bin` (plus manpage and
documentation in `C:/msys64/mingw64/share/...`) with
`cmake --install . --prefix /mingw64`
To be able to view the manpage, you need to install the manpage
viewer with "`pacman -S man`".
To run **uxplay.exe** you need to install some gstreamer plugin packages
with `pacman -S mingw-w64-x86_64-gst-<plugin>`, where the required ones
have `<plugin>` given by
1. **libav**
2. **plugins-good**
3. **plugins-bad**
Other possible MSYS2 gstreamer plugin packages you might use are listed
in [MSYS2 packages](https://packages.msys2.org/package/).
You also will need to grant permission to the uxplay executable
uxplay.exe to access data through the Windows firewall. You may
automatically be offered the choice to do this when you first run
uxplay, or you may need to do it using **Windows Settings-\>Update and
Security-\>Windows Security-\>Firewall & network protection -\> allow an
app through firewall**. If your virus protection flags uxplay.exe as
"suspicious" (but without a true malware signature) you may need to give
it an exception.
Now test by running "`uxplay`" (in a MSYS2 terminal window). If you need
to specify the audiosink, there are two main choices on Windows: the
older DirectSound plugin "`-as directsoundsink`", and the more modern
Windows Audio Session API (wasapi) plugin "`-as wasapisink`", which
supports [additional
options](https://gstreamer.freedesktop.org/documentation/wasapi/wasapisink.html)
such as
uxplay -as 'wasapisink device=\"<guid>\"'
where `<guid>` specifies an available audio device by its GUID, which
can be found using "`gst-device-monitor-1.0 Audio`": `<guid>` has a form
like `\{0.0.0.00000000\}.\{98e35b2b-8eba-412e-b840-fd2c2492cf44\}`. If
"`device`" is not specified, the default audio device is used.
If you wish to specify the videosink using the `-vs <videosink>` option,
some choices for `<videosink>` are `d3d11videosink`, `d3dvideosink`,
`glimagesink`, `gtksink`.
- With Direct3D 11.0 or greater, you can either always be in
fullscreen mode using option
`-vs "d3d11videosink fullscreen-toggle-mode=property fullscreen=true"`,
or get the ability to toggle into and out of fullscreen mode using
the Alt-Enter key combination with option
`-vs "d3d11videosink fullscreen-toggle-mode=alt-enter"`. For
convenience, these options will be added if just
`-vs d3d11videosink` with or without the fullscreen option "-fs" is
used. *(Windows users may wish to add "`vs d3d11videosink`" (no
initial "`-`") to the UxPlay startup options file; see "man uxplay"
or "uxplay -h".)*
The executable uxplay.exe can also be run without the MSYS2 environment,
in the Windows Terminal, with `C:\msys64\mingw64\bin\uxplay`.
# Usage
Options:
- These can also be written (one option per line, without the initial
"`-`" character) in the UxPlay startup file (either given by
environment variable `$UXPLAYRC`, or `~/.uxplayrc` or
`~/.config/uxplayrc`); lines begining with "`#`" are treated as
comments, and ignored. Command line options supersede options in the
startup file.
**-n server_name** (Default: UxPlay); server_name@\_hostname\_ will be
the name that appears offering AirPlay services to your iPad, iPhone
etc, where *hostname* is the name of the server running uxplay. This
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.
**-h265** Activate "ScreenMultiCodec" support (AirPlay "Features" bit
42) for accepting h265 (4K/HEVC) video in addition to h264 video (1080p)
in screen-mirror mode. When this option is used, two "video pipelines"
(one for h264, one for h265) are created. If any GStreamer plugins in
the pipeline are specific for h264 or h265, the correct version will be
used in each pipeline. A wired Client-Server ethernet connection is
preferred over Wifi for 4K video, and might be required by the client.
Only recent Apple devices (M1/M2 Macs or iPads, and some iPhones) can
send h265 video if a resolution "-s wxh" with h \> 1080 is requested.
The "-h265" option changes the default resolution ("-s" option) from
1920x1080 to 3840x2160, and leaves default maximum framerate ("-fps"
option) at 30fps.
**-hls \[v\]** Activate HTTP Live Streaming support. With this option
YouTube videos can be streamed directly from YouTube servers to UxPlay
(without passing through the client) by clicking on the AirPlay icon in
the YouTube app. Optional \[v\] (allowed values 2 or 3, default: 3)
allows selection of the version of GStreamer's \"playbin\" video player
to use for playing HLS video. *(Playbin v3 is the recommended player,
but if some videos fail to play, you can try with version 2.)*
**-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. 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). 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 (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.)*