forked from antimof/UxPlay
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
1708 lines (1417 loc) · 86.4 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.66: 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).
## 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. **There is no support for Airplay2
video-streaming protocol, and none is planned.**
- 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 4 Model B
and Pi 3 model B+.*
- Support for running on Microsoft Windows (builds with the MinGW-64
compiler in the unix-like MSYS2 environment).
## 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.
This can be used to build 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.)
- On Linux and \*BSD the mDNS/DNS-SD (Bonjour/ZeroConf) local network
services needed by UxPlay are usually provided by Avahi: **if there
is a firewall on the server that will host UxPlay, make sure the
default network port for mDNS queries (UDP 5353) is open**. (Uxplay
can work without this port by using only the host's loopback
interface, but its visibility to clients will be degraded.) See the
[Troubleshooting](#troubleshooting) section below for more details.
(With a firewall, you also need to open ports for UxPlay, and use
the `-p <n>` 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 hardware-accelerated video decoding on Raspberry Pi, Ubuntu \<
23.04 needs GStreamer to be
[patched](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
(recommended but optional for Raspberry Pi OS (Bullseye), no longer
needed for Manjaro \>= 23.02). *(Only these three distributions
supply a kernel module maintained by Raspberry Pi outside the
mainline Linux kernel that accesses the firmware decoder in the
Broadcom GPU)*.
- 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 13.3 (Intel and M2), FreeBSD
13.2, Windows 10 and 11 (64 bit).
On Raspberry Pi 4 model B, it is tested on Raspberry Pi OS (Bullseye)
(32- and 64-bit), Ubuntu 22.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+.
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), but both video
and audio content from DRM-free apps like "YouTube app" will be
streamed by UxPlay in Mirror mode.**
- **As UxPlay does not support non-Mirror AirPlay2 video streaming
(where the client controls a web server on the AirPlay server that
directly receives content to avoid it being decoded and re-encoded
by the client), 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 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 the Raspberry Pi Broadcom 2835 GPU**
Raspberry Pi (RPi) computers (tested on Pi 4 Model B) can now run
UxPlay using software video decoding, but hardware-accelerated
decoding by firmware in the Pi's GPU is prefered. UxPlay accesses
this using the GStreamer-1.22 Video4Linux2 (v4l2) plugin; the plugin
from older GStreamer needs a patch to backport fixes from v1.22
(already applied in Raspberry Pi OS (Bullseye), and available for
1.18.4 and later in the [UxPlay
Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)).
Also requires 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.
### 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.5 is installed: "`sudo apt-get 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).
- 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-get 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-get install libssl-dev libplist-dev`". (*unless you need
to build OpenSSL and libplist from source*).
2. `sudo apt-get install libavahi-compat-libdnssd-dev`
3. `sudo apt-get 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 for building a rpm package with rpmbuild**. See
["Packaging Status"](#packaging-status-linux-and-bsd-distributions)
section above.
- **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.
## Running UxPlay
### Installing plugins (Debian-based Linux systems) (*skip if you built a complete GStreamer from source*)
Next install the GStreamer plugins that are needed with
`sudo apt-get 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).
Plugins that may also be needed include "**gl**" for OpenGL support
(which may be useful, and should be used with h264 decoding by the
NVIDIA GPU), 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 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.
- 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).
- In Mirror mode, GStreamer has a choice of **two** methods to play
video with its accompanying audio: prior to UxPlay-1.64, the video
and audio streams were both played as soon as possible after they
arrived (the GStreamer "*sync=false*" method), with a GStreamer
internal clock used to try to keep them synchronized. **Starting
with UxPlay-1.64, the other method (GStreamer's "*sync=true*" mode),
which uses timestamps in the audio and video streams sent by the
client, is the new default**. On low-decoding-power UxPlay hosts
(such as Raspberry Pi 3 models) this will drop video frames that
cannot be decoded in time to play with the audio, making the video
jerky, but still synchronized.
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.
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).
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 R Pi 4 model B 8GB and R Pi 3 model B+)**:
- If you use the software-only (h264) video-decoding UxPlay option
`-avdec`, it now works better than earlier, with the new default
timestamp-based synchronization to keep audio and video
synchronized.
- For best performance, the Raspberry Pi needs the GStreamer
Video4linux2 plugin to use its Broadcom GPU hardware for decoding
h264 video. This needs the bcm2835_codec kernel module which is
maintained outside the mainline Linux kernel by Raspberry Pi in the
the [Raspberry Pi kernel
tree](https://github.com/raspberrypi/linux), and the only
distributions for R Pi that are known to supply it include Raspberry
Pi OS, Ubuntu, and Manjaro (all available from Raspberry Pi with
their Raspberry Pi Imager). Other distributions generally do not
provide it: **without this kernel module, UxPlay cannot use the
decoding firmware in the GPU.**
- On a Raspberry Pi model 4B running the unsupported "Legacy" R Pi OS
(Buster), note that this comes with a very old GStreamer-1.14.4
**that cannot be patched to access the Broadcom GPU**. If you need
to stay on the unsupported "Legacy" OS ("Lite" version), but want to
use UxPlay with hardware video decoding, you need to first build a
complete newer GStreamer 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. Note that a model 3B+ Pi running the Legacy
OS can access the GPU with GStreamer-1.14's omx plugin (use option
"`-vd omxh264dec`"), but this plugin is broken on model 4B's
firmware, and omx support was removed in R Pi OS (Bullseye).
For use of the GPU, use raspi-config "Performance Options" (on Raspberry
Pi OS, use a similar tool on other distributions) to allocate sufficient
memory for the GPU (on R. Pi 3 model B+, the maximum (256MB) is
suggested). Even with GPU video decoding, some frames may be dropped by
the lower-power 3 B+ to keep audio and video synchronized using
timestamps.
- The plugin in the latest GStreamer-1.22 release works well, but
older releases of GStreamer will not work unless patched with
backports from GStreamer-1.22. Raspberry Pi OS (Bullseye) now has a
working backport. For a fuller backport, or for other distributions,
patches for the GStreamer Video4Linux2 plugin are [available with
instructions in the UxPlay
Wiki](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches).
The basic uxplay options for R Pi are `uxplay [-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
try to find the best video solution by itself) provides the best
results** (the `-rpi*` options may be removed in a future release of
UxPlay.)
- If you are using Raspberry Pi OS (Bullseye) with Video4Linux2 from
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 patch
from the UxPlay Wiki has been applied.)
- 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)/lib/gstreamer-1.0` where
`(HOMEBREW)/*` 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).
**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`
Note that libplist will be linked statically to the uxplay
executable. 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 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, this option will be added if just `-vs d3d11videosink` (by
itself) is used. (You 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.
**-vsync \[x\]** (In Mirror mode:) this option (**now the default**)
uses timestamps to synchronize audio with video on the server, with an
optional audio delay in (decimal) milliseconds (*x* = "20.5" means
0.0205 seconds delay: positive or negative delays less than a second are
allowed.) It is needed on low-power systems such as Raspberry Pi without
hardware video decoding.
**-vsync no** (In Mirror mode:) this switches off timestamp-based
audio-video synchronization, restoring the default behavior prior to
UxPlay-1.64. Standard desktop systems seem to work well without use of
timestamps: this mode is appropriate for "live streaming" such as using
UxPlay as a second monitor for a mac computer, or monitoring a webcam;
with it, no video frames are dropped.
**-async \[x\]** (In Audio-Only (ALAC) mode:) this option uses
timestamps to synchronize audio on the server with video on the client,
with an optional audio delay in (decimal) milliseconds (*x* = "20.5"
means 0.0205 seconds delay: positive or negative delays less than a
second are allowed.) Because the client adds a video delay to account
for latency, the server in -async mode adds an equivalent audio delay,
which means that audio changes such as a pause or a track-change will
not take effect immediately. *This might in principle be mitigated by
using the `-al` audio latency setting to change the latency (default
0.25 secs) that the server reports to the client, but at present
changing this does not seem to have any effect*.
**-async no**. This is the still the default behavior in Audio-only
mode, but this option may be useful as a command-line option to switch
off a `-async` option set in a "uxplayrc" configuration file.
**-s wxh** (e.g. -s 1920x1080 , which is the default ) sets the display
resolution (width and height, in pixels). (This may be a request made to
the AirPlay client, and perhaps will not be the final resolution you
get.) w and h are whole numbers with four digits or less. Note that the
**height** pixel size is the controlling one used by the client for
determining the streaming format; the width is dynamically adjusted to
the shape of the image (portrait or landscape format, depending on how
an iPad is held, for example).
**-s wxh@r** As above, but also informs the AirPlay client about the
screen refresh rate of the display. Default is r=60 (60 Hz); r must be a
whole number less than 256.
**-o** turns on an "overscanned" option for the display window. This
reduces the image resolution by using some of the pixels requested by
option -s wxh (or their default values 1920x1080) by adding an empty
boundary frame of unused pixels (which would be lost in a full-screen
display that overscans, and is not displayed by gstreamer).
Recommendation: **don't use this option** unless there is some special
reason to use it.
**-fs** uses fullscreen mode, but only works with X11, Wayland or VAAPI.
**-p** allows you to select the network ports used by UxPlay (these need
to be opened if the server is behind a firewall). By itself, -p sets
"legacy" ports TCP 7100, 7000, 7001, UDP 6000, 6001, 7011. -p n (e.g. -p
35000) sets TCP and UDP ports n, n+1, n+2. -p n1,n2,n3 (comma-separated
values) sets each port separately; -p n1,n2 sets ports n1,n2,n2+1. -p
tcp n or -p udp n sets just the TCP or UDP ports. Ports must be in the
range \[1024-65535\].
If the -p option is not used, the ports are chosen dynamically
(randomly), which will not work if a firewall is running.
**-avdec** forces use of software h264 decoding using Gstreamer element
avdec_h264 (libav h264 decoder). This option should prevent
autovideosink choosing a hardware-accelerated videosink plugin such as
vaapisink.
**-vp *parser*** choses the GStreamer pipeline's h264 parser element,
default is h264parse. Using quotes "..." allows options to be added.
**-vd *decoder*** chooses the GStreamer pipeline's h264 decoder element,
instead of the default value "decodebin" which chooses it for you.
Software decoding is done by avdec_h264; various hardware decoders
include: vaapih264dec, nvdec, nvh264dec, v4l2h264dec (these require that
the appropriate hardware is available). Using quotes "..." allows some
parameters to be included with the decoder name.
**-vc *converter*** chooses the GStreamer pipeline's videoconverter
element, instead of the default value "videoconvert". When using
Video4Linux2 hardware-decoding by a GPU,`-vc v4l2convert` will also use
the GPU for video conversion. Using quotes "..." allows some parameters
to be included with the converter name.
**-vs *videosink*** chooses the GStreamer videosink, instead of the
default value "autovideosink" which chooses it for you. Some videosink
choices are: ximagesink, xvimagesink, vaapisink (for intel graphics),
gtksink, glimagesink, waylandsink, osxvideosink (for macOS), kmssink
(for systems without X11, like Raspberry Pi OS lite) or fpsdisplaysink
(which shows the streaming framerate in fps). Using quotes "..." 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 might not work on your system.
**-vs 0** suppresses display of streamed video, but plays streamed
audio. (The client's screen is still mirrored at a reduced rate of 1
frame per second, but is not rendered or displayed.) This feature (which
streams audio in AAC audio format) is now probably unneeded, as UxPlay
can now stream superior-quality Apple Lossless audio without video in
Airplay non-mirror mode.
**-v4l2** Video settings for hardware h264 video decoding in the GPU by
Video4Linux2. Equivalent to `-vd v4l2h264dec -vc v4l2convert`.
**-bt709** A workaround for the failure of the older Video4Linux2 plugin
to recognize Apple's 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.
**-rpigl** Equivalent to "-rpi -vs glimagesink". Sometimes better for
"Desktop" Raspberry Pi systems with X11.
**-rpifb** Equivalent to "-rpi -vs kmssink" (use for Raspberry Pi
systems using the framebuffer, like RPi OS Bullseye Lite).
**-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).
**-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.)
**-as 0** (or just **-a**) suppresses playing of streamed audio, but
displays streamed video.
**-al *x*** specifies an audio latency *x* in (decimal) seconds in
Audio-only (ALAC), that is reported to the client. Values in the range
\[0.0, 10.0\] seconds are allowed, and will be converted to a whole
number of microseconds. Default is 0.25 sec (250000 usec). *(However,
the client appears to ignore this reported latency, so this option seems
non-functional.)*
**-ca *filename*** provides a file (where *filename* can include a full