forked from FDH2/UxPlay
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.html
1658 lines (1658 loc) · 97.1 KB
/
README.html
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
<h1
id="uxplay-1.66-airplay-mirror-and-airplay-audio-server-for-linux-macos-and-unix-now-also-runs-on-windows.">UxPlay
1.66: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix
(now also runs on Windows).</h1>
<h3
id="now-developed-at-the-github-site-httpsgithub.comfdh2uxplay-where-all-user-issues-should-be-posted.">Now
developed at the GitHub site <a
href="https://github.com/FDH2/UxPlay">https://github.com/FDH2/UxPlay</a>
(where all user issues should be posted).</h3>
<h2 id="highlights">Highlights:</h2>
<ul>
<li>GPLv3, open source.</li>
<li>Originally supported only AirPlay Mirror protocol, now has added
support for AirPlay Audio-only (Apple Lossless ALAC) streaming from
current iOS/iPadOS clients. <strong>There is no support for Airplay2
video-streaming protocol, and none is planned.</strong></li>
<li>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.</li>
<li>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.</li>
<li>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).</li>
<li>Support for server behind a firewall.</li>
<li>Raspberry Pi support <strong>both with and without hardware video
decoding</strong> by the Broadcom GPU. <em>Tested on Raspberry Pi 4
Model B and Pi 3 model B+.</em></li>
<li>Support for running on Microsoft Windows (builds with the MinGW-64
compiler in the unix-like MSYS2 environment).</li>
</ul>
<h2 id="packaging-status-linux-and-bsd-distributions">Packaging status
(Linux and *BSD distributions)</h2>
<p><a href="https://repology.org/project/uxplay/versions"><img
src="https://repology.org/badge/vertical-allrepos/uxplay.svg"
alt="Current Packaging status" /></a>.</p>
<ul>
<li><p>Install uxplay on Debian-based Linux systems with
“<code>sudo apt install uxplay</code>”; on FreeBSD with
“<code>sudo pkg install uxplay</code>”. Also available on Arch-based
systems through AUR. Since v. 1.66, uxplay is now also packaged in RPM
format by Fedora 38 (“<code>sudo dnf install uxplay</code>”).</p></li>
<li><p>For other RPM-based distributions which have not yet packaged
UxPlay, a RPM “specfile” <strong>uxplay.spec</strong> is now provided
with recent <a
href="https://github.com/FDH2/UxPlay/releases">releases</a> (see their
“Assets”), and can also be found in the UxPlay source top directory. See
the section on using this specfile for <a
href="#building-an-installable-rpm-package">building an installable RPM
package</a>.</p></li>
</ul>
<p>After installation:</p>
<ul>
<li><p>(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 <a
href="#troubleshooting">Troubleshooting</a> below for more details);
also open three UDP and three TCP ports for Uxplay, and use the “uxplay
-p <n>” option (see “<code>man uxplay</code>” or
“<code>uxplay -h</code>”).</p></li>
<li><p>Even if you install your distribution’s pre-compiled uxplay
binary package, you may need to read the instructions below for <a
href="#running-uxplay">running UxPlay</a> to see which of your
distribution’s <strong>GStreamer plugin packages</strong> you should
also install.</p></li>
<li><p>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.</p></li>
<li><p>Add any UxPlay options you want to use as defaults to a startup
file <code>~/.uxplayrc</code> (see “<code>man uxplay</code>” or
“<code>uxplay -h</code>” for format and other possible
locations).</p></li>
<li><p>On Raspberry Pi: If you use Ubuntu 22.10 or earlier, GStreamer
must be <a
href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patched</a>
to use hardware video decoding by the Broadcom GPU (also recommended but
optional for Raspberry Pi OS (Bullseye): use option
“<code>uxplay -bt709</code>” if you do not use the patch).</p></li>
</ul>
<p>To (easily) compile the latest UxPlay from source, see the section <a
href="#getting-uxplay">Getting UxPlay</a>.</p>
<h1 id="detailed-description-of-uxplay">Detailed description of
UxPlay</h1>
<p>This project is a GPLv3 open source unix AirPlay2 Mirror server for
Linux, macOS, and *BSD. It was initially developed by <a
href="http://github.com/antimof/Uxplay">antimof</a> using code from
OpenMAX-based <a href="https://github.com/FD-/RPiPlay">RPiPlay</a>,
which in turn derives from <a
href="https://github.com/KqsMea8/AirplayServer">AirplayServer</a>, <a
href="https://github.com/juhovh/shairplay">shairplay</a>, and <a
href="https://github.com/EstebanKubata/playfair">playfair</a>. (The
antimof site is no longer involved in development, but periodically
posts updates pulled from the new main <a
href="https://github.com/FDH2/UxPlay">UxPlay site</a>).</p>
<p>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).</p>
<p>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+.</p>
<p>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 <a
href="https://openairplay.github.io/airplay-spec/">here</a>, <a
href="https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol">here</a>
and <a href="https://emanuelecozzi.net/docs/airplay2">here</a>; see also
<a href="https://pyatv.dev/documentation/protocols">pyatv</a> 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.</p>
<p>The UxPlay server and its client must be on the same local area
network, on which a <strong>Bonjour/Zeroconf mDNS/DNS-SD server</strong>
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 <a href="https://www.avahi.org">Avahi</a>, through
the avahi-daemon service, and is included in most Linux distributions
(this service can also be provided by macOS, iOS or Windows
servers).</p>
<p>Connections to the UxPlay server by iOS/MacOS clients can be
initiated both in <strong>AirPlay Mirror</strong> mode (which streams
lossily-compressed AAC audio while mirroring the client screen, or in
the alternative <strong>AirPlay Audio</strong> mode which streams Apple
Lossless (ALAC) audio without screen mirroring. In
<strong>Audio</strong> mode, metadata is displayed in the uxplay
terminal; if UxPlay option <code>-ca <name></code> is used, the
accompanying cover art is also output to a periodically-updated file
<code><name></code>, and can be viewed with a (reloading) graphics
viewer of your choice. <em>Switching between</em>
<strong>Mirror</strong> <em>and</em> <strong>Audio</strong> <em>modes
during an active connection is possible: in</em> <strong>Mirror</strong>
<em>mode, stop mirroring (or close the mirror window) and start an</em>
<strong>Audio</strong> <em>mode connection, switch back by initiating
a</em> <strong>Mirror</strong> <em>mode connection; cover-art display
stops/restarts as you leave/re-enter</em> <strong>Audio</strong>
<em>mode.</em></p>
<ul>
<li><p><strong>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.</strong></p></li>
<li><p><strong>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.</strong></p></li>
</ul>
<h3
id="possibility-for-using-hardware-accelerated-h264-video-decoding-if-available.">Possibility
for using hardware-accelerated h264 video-decoding, if available.</h3>
<p>UxPlay uses <a href="https://gstreamer.freedesktop.org">GStreamer</a>
“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.</p>
<ul>
<li><p><strong>VAAPI for Intel and AMD integrated graphics, NVIDIA with
“Nouveau” open-source driver</strong></p>
<p>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 <a
href="https://nouveau.freedesktop.org/VideoAcceleration.html">here</a>,
but this requires VAAPI to be supplemented with firmware extracted from
the proprietary NVIDIA drivers.</p></li>
<li><p><strong>NVIDIA with proprietary drivers</strong></p>
<p>The <code>nvh264dec</code> 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
<code>libcuda.so</code> is installed. For GStreamer-1.16.3 or earlier,
the plugin is called <code>nvdec</code>, and must be <a
href="https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins">built
by the user</a>.</p></li>
<li><p><strong>Video4Linux2 support for the Raspberry Pi Broadcom 2835
GPU</strong></p>
<p>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 <a
href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">UxPlay
Wiki</a>). 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. <em>Note: The latest Raspberry Pi model 5 does
not provide hardware-accelerated (GPU) H264 decoding as its CPU is
powerful enough for satisfactory software decoding.</em></p></li>
</ul>
<h3 id="note-to-packagers">Note to packagers:</h3>
<p>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 <strong>prior to v. 3.0.0</strong> (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.</p>
<h1 id="getting-uxplay">Getting UxPlay</h1>
<p>Either download and unzip <a
href="https://github.com/FDH2/UxPlay/archive/refs/heads/master.zip">UxPlay-master.zip</a>,
or (if git is installed): “git clone https://github.com/FDH2/UxPlay”.
You can also download a recent or earlier version listed in <a
href="https://github.com/FDH2/UxPlay/releases">Releases</a>.</p>
<ul>
<li>A recent UxPlay can also be found on the original <a
href="https://github.com/antimof/UxPlay">antimof site</a>; that original
project is inactive, but is usually kept current or almost-current with
the <a href="https://github.com/FDH2/UxPlay">active UxPlay github
site</a> (thank you antimof!).</li>
</ul>
<h2 id="building-uxplay-on-linux-or-bsd">Building UxPlay on Linux (or
*BSD):</h2>
<h3 id="debian-based-systems">Debian-based systems:</h3>
<p>(Adapt these instructions for non-Debian-based Linuxes or *BSD; for
macOS, see specific instruction below). See <a
href="#troubleshooting">Troubleshooting</a> below for help with any
difficulties.</p>
<p>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 “<code>which pkg-config</code>”,
install pkg-config or its work-alike replacement pkgconf. Also make sure
that cmake>=3.5 is installed:
“<code>sudo apt-get install cmake</code>” (add
<code>build-essential</code> and <code>pkg-config</code> (or
<code>pkgconf</code>) to this if needed).</p>
<p>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 (<em>e.g.</em> ,
“<code>export OPENSSL_ROOT_DIR=/usr/local/lib64</code>” if that is where
it is installed).</p>
<ul>
<li>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 <a
href="https://github.com/FDH2/UxPlay/wiki/Building-latest-GStreamer-from-source-on-distributions-with-older-GStreamer-(e.g.-Raspberry-Pi-OS-).">these
instructions</a> . <strong>Do this <em>before</em> building
UxPlay</strong>.</li>
</ul>
<p>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:</p>
<p><strong>Note:</strong> 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
<code>-DNO_MARCH_NATIVE=ON</code>.</p>
<p>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 <strong>IF</strong> the X11 development libraries are
installed and detected. Install these with
“<code>sudo apt-get install libx11-dev</code>”. If GStreamer < 1.20
is detected, a fix needed by screen-sharing apps (<em>e.g.</em>, Zoom)
will also be made.</p>
<ul>
<li>If X11 development libraries are present, but you wish to build
UxPlay <em>without</em> any X11 dependence, use the cmake option
<code>-DNO_X11_DEPS=ON</code>.</li>
</ul>
<ol type="1">
<li><code>sudo apt-get install libssl-dev libplist-dev</code>“.
(<em>unless you need to build OpenSSL and libplist from
source</em>).</li>
<li><code>sudo apt-get install libavahi-compat-libdnssd-dev</code></li>
<li><code>sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev</code>.
(*<em>Skip if you built Gstreamer from source</em>)</li>
<li><code>cmake .</code> (<em>For a cleaner build, which is useful if
you modify the source, replace this by</em>
“<code>mkdir build; cd build; cmake ..</code>”: <em>you can then delete
the contents of the <code>build</code> directory if needed, without
affecting the source.</em>) Also add any cmake “<code>-D</code>” options
here as needed (e.g, <code>-DNO_X11_DEPS=ON</code> or
<code>-DNO_MARCH_NATIVE=ON</code>).</li>
<li><code>make</code></li>
<li><code>sudo make install</code> (you can afterwards uninstall with
<code>sudo make uninstall</code> in the same directory in which this was
run).</li>
</ol>
<p>This installs the executable file “<code>uxplay</code>” to
<code>/usr/local/bin</code>, (and installs a manpage to somewhere
standard like <code>/usr/local/share/man/man1</code> and README files to
somewhere like <code>/usr/local/share/doc/uxplay</code>). (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).</p>
<h3 id="building-on-non-debian-linux-and-bsd">Building on non-Debian
Linux and *BSD</h3>
<p>**For those with RPM-based distributions, a RPM spec file uxplay.spec
is also available: see <a
href="#building-an-installable-rpm-package">Building an installable rpm
package</a>.</p>
<ul>
<li><p><strong>Red Hat, or clones like CentOS (now continued as Rocky
Linux or Alma Linux):</strong> (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) <em>(some of these may be in the “CodeReady” add-on
repository, called “PowerTools” by clones)</em></p></li>
<li><p><strong>Mageia, PCLinuxOS, OpenMandriva:</strong> 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.</p></li>
<li><p><strong>openSUSE:</strong> (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).</p></li>
<li><p><strong>Arch Linux</strong> (<em>Also available as a package in
AUR</em>): (sudo pacman -Syu) openssl libplist avahi
gst-plugins-base.</p></li>
<li><p><strong>FreeBSD:</strong> (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.</p></li>
</ul>
<h4 id="building-an-installable-rpm-package">Building an installable RPM
package</h4>
<p>First-time RPM builders should first install the rpm-build and
rpmdevtools packages, then create the rpmbuild tree with
“<code>rpmdev-setuptree</code>”. Then download and copy uxplay.spec into
<code>~/rpmbuild/SPECS</code>. In that directory, run
“<code>rpmdev-spectool -g -R uxplay.spec</code>” to download the
corresponding source file <code>uxplay-*.tar.gz</code> into
<code>~/rpmbuild/SOURCES</code> (“rpmdev-spectool” may also be just
called “spectool”); then run “<code>rpmbuild -ba uxplay.spec</code>”
(you will need to install any required dependencies this reports). This
should create the uxplay RPM package in a subdirectory of
<code>~/rpmbuild/RPMS</code>. (<strong>uxplay.spec</strong> 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.)</p>
<h2 id="running-uxplay">Running UxPlay</h2>
<h3
id="installing-plugins-debian-based-linux-systems-skip-if-you-built-a-complete-gstreamer-from-source">Installing
plugins (Debian-based Linux systems) (<em>skip if you built a complete
GStreamer from source</em>)</h3>
<p>Next install the GStreamer plugins that are needed with
<code>sudo apt-get install gstreamer1.0-<plugin></code>. Values of
<code><plugin></code> required are:</p>
<ol type="1">
<li>“<strong>plugins-base</strong>”</li>
<li>“<strong>libav</strong>” (for sound),</li>
<li>“<strong>plugins-good</strong>” (for v4l2 hardware h264
decoding)</li>
<li>“<strong>plugins-bad</strong>” (for h264 decoding).</li>
</ol>
<p>Plugins that may also be needed include “<strong>gl</strong>” for
OpenGL support (which may be useful, and should be used with h264
decoding by the NVIDIA GPU), and “<strong>x</strong>” for X11 support,
although these may already be installed; “<strong>vaapi</strong>” 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,
“<strong>alsa</strong>”“,”<strong>pulseaudio</strong>”, or
“<strong>pipewire</strong>” plugins may need to be installed, depending
on how your audio is set up.</p>
<ul>
<li>Also install “<strong>gstreamer1.0-tools</strong>” to get the
utility gst-inspect-1.0 for examining the GStreamer installation.</li>
</ul>
<h3
id="installing-plugins-non-debian-based-linux-or-bsd-skip-if-you-built-a-complete-gstreamer-from-source">Installing
plugins (Non-Debian-based Linux or *BSD) (<em>skip if you built a
complete GStreamer from source</em>)</h3>
<p>In some cases, because of patent issues, the libav plugin feature
<strong>avdec_aac</strong> needed for decoding AAC audio in mirror mode
is not provided in the official distribution: get it from community
repositories for those distributions.</p>
<ul>
<li><p><strong>Red Hat, or clones like CentOS (now continued as Rocky
Linux or Alma Linux):</strong> Install gstreamer1-libav
gstreamer1-plugins-bad-free (+ gstreamer1-vaapi for Intel/AMD graphics).
In recent Fedora, gstreamer1-libav is renamed gstreamer1-plugin-libav.
<strong>To get avdec_aac, install packages from <a
href="https://rpmfusion.org">rpmfusion.org</a></strong>: (get
ffmpeg-libs from rpmfusion; on RHEL or clones, but not recent Fedora,
also get gstreamer1-libav from there).</p></li>
<li><p><strong>Mageia, PCLinuxOS, OpenMandriva:</strong> Install
gstreamer1.0-libav gstreamer1.0-plugins-bad (+ gstreamer1.0-vaapi for
Intel/AMD graphics). <strong>On Mageia, to get avdec_aac, install ffmpeg
from the “tainted” repository</strong>, (which also provides a more
complete gstreamer1.0-plugins-bad).</p></li>
<li><p><strong>openSUSE:</strong> Install gstreamer-plugins-libav
gstreamer-plugins-bad (+ gstreamer-plugins-vaapi for Intel/AMD
graphics). <strong>To get avdec_aac, install libav* packages for
openSUSE from <a
href="https://ftp.gwdg.de/pub/linux/misc/packman/suse/">Packman</a>
“Essentials”</strong>; recommendation: after adding the Packman
repository, use the option in YaST Software management to switch all
system packages for multimedia to Packman).</p></li>
<li><p><strong>Arch Linux</strong> Install gst-plugins-good
gst-plugins-bad gst-libav (+ gstreamer-vaapi for Intel/AMD
graphics).</p></li>
<li><p><strong>FreeBSD:</strong> Install gstreamer1-libav,
gstreamer1-plugins, gstreamer1-plugins-* (* = core, good, bad, x, gtk,
gl, vulkan, pulse, v4l2, …), (+ gstreamer1-vaapi for Intel/AMD
graphics).</p></li>
</ul>
<h3 id="starting-and-running-uxplay">Starting and running UxPlay</h3>
<p>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 <code>$UXPLAYRC</code>, (2)
<code>~/.uxplayrc</code> in the user’s home directory (“~”), (3)
<code>~/.config/uxplayrc</code>. The format is one option per line,
omitting the initial <code>"-"</code> of the command-line option. Lines
in the configuration file beginning with <code>"#"</code> are treated as
comments and ignored.</p>
<p><strong>Run uxplay in a terminal window</strong>. 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
<code>systemctl status avahi-daemon</code>. If this shows the
avahi-daemon is not running, control it with
<code>sudo systemctl [start,stop,enable,disable] avahi-daemon</code> (on
non-systemd systems, such as *BSD, use
<code>sudo service avahi-daemon [status, start, stop, restart, ...]</code>).
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: <strong>if a firewall is active, also open UDP port 5353 (for
mDNS queries) needed by Avahi</strong>. See <a
href="#troubleshooting">Troubleshooting</a> below for help with this or
other problems.</p>
<ul>
<li><p>By default, UxPlay is locked to its current client until that
client drops the connection; since UxPlay-1.58, the option
<code>-nohold</code> 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 ( <code>-restrict</code>,
<code>-allow <id></code>, <code>-block <id></code>) to
control which clients are allowed to connect, using their “deviceID”
(which appears to be immutable).</p></li>
<li><p>In Mirror mode, GStreamer has a choice of <strong>two</strong>
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 “<em>sync=false</em>” method), with a
GStreamer internal clock used to try to keep them synchronized.
<strong>Starting with UxPlay-1.64, the other method (GStreamer’s
“<em>sync=true</em>” mode), which uses timestamps in the audio and video
streams sent by the client, is the new default</strong>. 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.</p></li>
</ul>
<p>The older method which does not drop late video frames worked well on
more powerful systems, and is still available with the UxPlay option
“<code>-vsync no</code>”; 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.)</p>
<ul>
<li>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 <code>-async</code> 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.</li>
</ul>
<p>The -vsync and -async options also allow an optional positive (or
negative) audio-delay adjustment in <em>milliseconds</em> for
fine-tuning : <code>-vsync 20.5</code> delays audio relative to video by
0.0205 secs; a negative value advances it.)</p>
<ul>
<li><p>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 <code>-vsync</code>.</p></li>
<li><p>Since UxPlay-1.54, you can display the accompanying “Cover Art”
from sources like Apple Music in Audio-Only (ALAC) mode: run
“<code>uxplay -ca <name> &</code>” in the background, then run
a image viewer with an autoreload feature: an example is “feh”: run
“<code>feh -R 1 <name></code>” in the foreground; terminate feh
and then Uxplay with “<code>ctrl-C fg ctrl-C</code>”.</p></li>
</ul>
<p>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
<code>-vs <videosink></code>. Which videosinks are available
depends on your operating system and graphics hardware: use
“<code>gst-inspect-1.0 | grep sink | grep -e video -e Video -e image</code>”
to see what is available. Some possibilites on Linux/*BSD are:</p>
<ul>
<li><p><strong>glimagesink</strong> (OpenGL),
<strong>waylandsink</strong></p></li>
<li><p><strong>xvimagesink</strong>, <strong>ximagesink</strong>
(X11)</p></li>
<li><p><strong>kmssink</strong>, <strong>fbdevsink</strong> (console
graphics without X11)</p></li>
<li><p><strong>vaapisink</strong> (for Intel/AMD hardware-accelerated
graphics); for NVIDIA hardware graphics (with CUDA) use
<strong>glimagesink</strong> combined with “<code>-vd nvh264dec</code>”
(or “nvh264sldec”, a new variant which will become “nvh264dec” in
GStreamer-1.24).</p></li>
</ul>
<p>GStreamer also searches for the best “audiosink”; override its choice
with <code>-as <audiosink></code>. Choices on Linux include
pulsesink, alsasink, pipewiresink, oss4sink; see what is available with
<code>gst-inspect-1.0 | grep sink | grep -e audio -e Audio</code>.</p>
<p><strong>One common problem involves GStreamer attempting to use
incorrectly-configured or absent accelerated hardware h264 video
decoding (e.g., VAAPI). Try “<code>uxplay -avdec</code>” 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.</strong></p>
<p>See <a href="#usage">Usage</a> for more run-time options.</p>
<h3
id="special-instructions-for-raspberry-pi-tested-on-r-pi-4-model-b-8gb-and-r-pi-3-model-b"><strong>Special
instructions for Raspberry Pi (tested on R Pi 4 model B 8GB and R Pi 3
model B+)</strong>:</h3>
<ul>
<li><p>If you use the software-only (h264) video-decoding UxPlay option
<code>-avdec</code>, it now works better than earlier, with the new
default timestamp-based synchronization to keep audio and video
synchronized.</p></li>
<li><p>For best performance, a Raspberry Pi <strong>older than model
5</strong> 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 <a
href="https://github.com/raspberrypi/linux">Raspberry Pi kernel
tree</a>, 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: <strong>without this kernel module, UxPlay
cannot use the decoding firmware in the GPU.</strong></p></li>
<li><p>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
<strong>that cannot be patched to access the Broadcom GPU</strong>. 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 <a
href="https://github.com/FDH2/UxPlay/wiki/Building-latest-GStreamer-from-source-on-distributions-with-older-GStreamer-(e.g.-Raspberry-Pi-OS-).">these
instructions</a> 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 “<code>-vd omxh264dec</code>”), but this plugin is
broken on model 4B’s firmware, and omx support was removed in R Pi OS
(Bullseye).</p></li>
</ul>
<p>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.</p>
<ul>
<li>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 <a
href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">available
with instructions in the UxPlay Wiki</a>.</li>
</ul>
<p>The basic uxplay options for R Pi are
<code>uxplay [-vs <videosink>]</code>. The choice
<code><videosink></code> = <code>glimagesink</code> is sometimes
useful. On a system without X11 (like R Pi OS Lite) with framebuffer
video, use <code><videosink></code> = <code>kmssink</code>. With
the Wayland video compositor, use <code><videosink></code> =
<code>waylandsink</code>. When using the Video4Linux2 plugin to access
hardware video decoding, an option <code>-v4l2</code> may be useful: for
convenience, this also comes combined with various videosink options as
<code>-rpi</code>, <code>-rpigl</code> <code>-rpifb</code>,
<code>-rpiwl</code>, respectively provided for X11, X11 with OpenGL,
framebuffer, and Wayland systems. <strong>You may find that just
“<code>uxplay</code>”, (<em>without</em> <code>-v4l2</code> or
<code>-rpi*</code> options, which lets GStreamer try to find the best
video solution by itself) provides the best results</strong> (the
<code>-rpi*</code> options may be removed in a future release of
UxPlay.)</p>
<ul>
<li><p>If you are using Raspberry Pi OS (Bullseye) with Video4Linux2
from unpatched GStreamer-1.18.4, you need the <code>-bt709</code> option
with UxPlay-1.56 or later. Also don’t use options <code>-v4l2</code> and
<code>-rpi*</code> 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.)</p></li>
<li><p>Tip: to start UxPlay on a remote host (such as a Raspberry Pi)
using ssh:</p></li>
</ul>
<pre><code> ssh user@remote_host
export DISPLAY=:0
nohup uxplay [options] > FILE &</code></pre>
<p>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)</p>
<h2
id="building-uxplay-on-macos-intel-x86_64-and-apple-silicon-m1m2-macs">Building
UxPlay on macOS: <strong>(Intel X86_64 and “Apple Silicon” M1/M2
Macs)</strong></h2>
<p><em>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.</em></p>
<p>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).</p>
<p>It is also assumed that CMake >= 3.13 is installed: this can be
done with package managers <a
href="http://www.macports.org">MacPorts</a>
(<code>sudo port install cmake</code>), <a
href="http://brew.sh">Homebrew</a> (<code>brew install cmake</code>), or
by a download from <a
href="https://cmake.org/download/">https://cmake.org/download/</a>. Also
install <code>git</code> if you will use it to fetch UxPlay.</p>
<p>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.</p>
<ul>
<li><p>If you use Homebrew:
<code>brew install libplist openssl@3</code></p></li>
<li><p>if you use MacPorts:
<code>sudo port install libplist-devel openssl3</code></p></li>
</ul>
<p>Otherwise, build libplist and openssl from source: see instructions
near the end of this README; requires development tools (autoconf,
automake, libtool, <em>etc.</em>) to be installed.</p>
<p>Next get the latest macOS release of GStreamer-1.0.</p>
<p><strong>Using “Official” GStreamer (Recommended for both MacPorts and
Homebrew users)</strong>: install the GStreamer release for macOS from
<a
href="https://gstreamer.freedesktop.org/download/">https://gstreamer.freedesktop.org/download/</a>.
(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 <strong>not</strong> install (or should uninstall) the GStreamer
supplied by their package manager, if they use the “official”
release.</p>
<ul>
<li>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.)</li>
</ul>
<p><strong>Using Homebrew’s GStreamer</strong>: 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 <a
href="https://formulae.brew.sh/formula/gstreamer#default">Homebrew
gstreamer installation</a> has recently been reworked into a single
“formula” named <code>gstreamer</code>, which now works without needing
GST_PLUGIN_PATH to be set in the enviroment. Homebrew installs gstreamer
to <code>(HOMEBREW)/lib/gstreamer-1.0</code> where
<code>(HOMEBREW)/*</code> is <code>/opt/homebrew/*</code> on Apple
Silicon Macs, and <code>/usr/local/*</code> 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).</p>
<p><strong>Using GStreamer installed from MacPorts</strong>: this is
<strong>not</strong> recommended, as currently the MacPorts GStreamer is
old (v1.16.2), unmaintained, and built to use X11:</p>
<ul>
<li>Instead <a
href="https://github.com/FDH2/UxPlay/wiki/Building-GStreamer-from-Source-on-macOS-with-MacPorts">build
gstreamer yourself</a> if you use MacPorts and do not want to use the
“Official” Gstreamer binaries.</li>
</ul>
<p><em>(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
<code>-DUSE_X11=ON</code>, and run it from an XQuartz terminal with -vs
ximagesink; older non-retina macs require a lower resolution when using
X11: <code>uxplay -s 800x600</code>.)</em></p>
<p>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).</p>
<ul>
<li><p>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.
<strong>Recommendation: use the new UxPlay “no timestamp” option
“<code>-vsync no</code>”</strong> (you can add a line “vsync no” in the
uxplayrc configuration file).</p></li>
<li><p>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.</p></li>
<li><p>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.</p></li>
<li><p>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.</p></li>
</ul>
<h2
id="building-uxplay-on-microsoft-windows-using-msys2-with-the-mingw-64-compiler.">Building
UxPlay on Microsoft Windows, using MSYS2 with the MinGW-64
compiler.</h2>
<ul>
<li>tested on Windows 10 and 11, 64-bit.</li>
</ul>
<ol type="1">
<li><p>Download and install <strong>Bonjour SDK for Windows
v3.0</strong>. You can download the SDK without any registration at <a
href="https://www.softpedia.com/get/Programming/SDK-DDK/Bonjour-SDK.shtml">softpedia.com</a>,
or get it from the official Apple site <a
href="https://developer.apple.com/download/all/?q=Bonjour%20SDK%20for%20Windows">https://developer.apple.com/download</a>
(Apple makes you register as a developer to access it from their site).
This should install the Bonjour SDK as
<code>C:\Program Files\Bonjour SDK</code>.</p></li>
<li><p>(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 <a
href="https://www.msys2.org">https://www.msys2.org/</a>. Accept the
default installation location <code>C:\mysys64</code>.</p></li>
<li><p><a href="https://packages.msys2.org/package/">MSYS2 packages</a>
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 <strong>MinGW-64</strong> compiler and
<strong>cmake</strong></p>
<pre><code>pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc</code></pre>
<p>The compiler with all required dependencies will be installed in the
msys64 directory, with default path <code>C:/msys64/mingw64</code>. Here
we will simply build UxPlay from the command line in the MSYS2
environment (this uses “<code>ninja</code>” in place of
“<code>make</code>” for the build system).</p></li>
<li><p>Download the latest UxPlay from github <strong>(to use
<code>git</code>, install it with <code>pacman -S git</code>, then
“<code>git clone https://github.com/FDH2/UxPlay</code>”)</strong>, then
install UxPlay dependencies (openssl is already installed with
MSYS2):</p>
<p><code>pacman -S mingw-w64-x86_64-libplist mingw-w64-x86_64-gstreamer mingw-w64-x86_64-gst-plugins-base</code></p>
<p>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 <a
href="https://gstreamer.freedesktop.org/download/">official GStreamer
site</a>, but only the MinGW 64-bit build on MSYS2 has been
tested.</p></li>
<li><p>cd to the UxPlay source directory, then
“<code>mkdir build</code>” and “<code>cd build</code>”. The build
process assumes that the Bonjour SDK is installed at
<code>C:\Program Files\Bonjour SDK</code>. If it is somewhere else, set
the enviroment variable BONJOUR_SDK_HOME to point to its location. Then
build UxPlay with</p>
<p><code>cmake ..</code></p>
<p><code>ninja</code></p></li>
<li><p>Assuming no error in either of these, you will have built the
uxplay executable <strong>uxplay.exe</strong> 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 <code>/mingw64/...</code> available, and you can
install the uxplay.exe executable in <code>C:/msys64/mingw64/bin</code>
(plus manpage and documentation in
<code>C:/msys64/mingw64/share/...</code>) with</p>
<p><code>cmake --install . --prefix /mingw64</code></p>
<p>To be able to view the manpage, you need to install the manpage
viewer with “<code>pacman -S man</code>”.</p></li>
</ol>
<p>To run <strong>uxplay.exe</strong> you need to install some gstreamer
plugin packages with
<code>pacman -S mingw-w64-x86_64-gst-<plugin></code>, where the
required ones have <code><plugin></code> given by</p>
<ol type="1">
<li><strong>libav</strong></li>
<li><strong>plugins-good</strong></li>
<li><strong>plugins-bad</strong></li>
</ol>
<p>Other possible MSYS2 gstreamer plugin packages you might use are
listed in <a href="https://packages.msys2.org/package/">MSYS2
packages</a>.</p>
<p>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 <strong>Windows
Settings->Update and Security->Windows Security->Firewall &
network protection -> allow an app through firewall</strong>. If your
virus protection flags uxplay.exe as “suspicious” (but without a true
malware signature) you may need to give it an exception.</p>
<p>Now test by running “<code>uxplay</code>” (in a MSYS2 terminal
window). If you need to specify the audiosink, there are two main
choices on Windows: the older DirectSound plugin
“<code>-as directsoundsink</code>”, and the more modern Windows Audio
Session API (wasapi) plugin “<code>-as wasapisink</code>”, which
supports <a
href="https://gstreamer.freedesktop.org/documentation/wasapi/wasapisink.html">additional
options</a> such as</p>
<pre><code>uxplay -as 'wasapisink device=\"<guid>\"' </code></pre>
<p>where <code><guid></code> specifies an available audio device
by its GUID, which can be found using
“<code>gst-device-monitor-1.0 Audio</code>”: <code><guid></code>
has a form like
<code>\{0.0.0.00000000\}.\{98e35b2b-8eba-412e-b840-fd2c2492cf44\}</code>.
If “<code>device</code>” is not specified, the default audio device is
used.</p>
<p>If you wish to specify the videosink using the
<code>-vs <videosink></code> option, some choices for
<code><videosink></code> are <code>d3d11videosink</code>,
<code>d3dvideosink</code>, <code>glimagesink</code>,
<code>gtksink</code>. 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
<code>-vs "d3d11videosink fullscreen-toggle-mode=alt-enter"</code>. For
convenience, this option will be added if just
<code>-vs d3d11videosink</code> (by itself) is used. (You may wish to
add “<code>vs d3d11videosink</code>” (no initial “<code>-</code>”) to
the UxPlay startup options file; see “man uxplay” or “uxplay -h”.)</p>
<p>The executable uxplay.exe can also be run without the MSYS2
environment, in the Windows Terminal, with
<code>C:\msys64\mingw64\bin\uxplay</code>.</p>
<h1 id="usage">Usage</h1>
<p>Options:</p>
<ul>
<li>These can also be written (one option per line, without the initial
“<code>-</code>” character) in the UxPlay startup file (either given by
environment variable <code>$UXPLAYRC</code>, or <code>~/.uxplayrc</code>
or <code>~/.config/uxplayrc</code>); lines begining with
“<code>#</code>” are treated as comments, and ignored. Command line
options supersede options in the startup file.</li>
</ul>
<p><strong>-n server_name</strong> (Default: UxPlay);
server_name@_hostname_ will be the name that appears offering AirPlay
services to your iPad, iPhone etc, where <em>hostname</em> is the name
of the server running uxplay. This will also now be the name shown above
the mirror display (X11) window.</p>
<p><strong>-nh</strong> Do not append “<span class="citation"
data-cites="_hostname_">@_hostname_</span>” at the end of the AirPlay
server name.</p>
<p><strong>-vsync [x]</strong> (In Mirror mode:) this option
(<strong>now the default</strong>) uses timestamps to synchronize audio
with video on the server, with an optional audio delay in (decimal)
milliseconds (<em>x</em> = “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.</p>
<p><strong>-vsync no</strong> (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.</p>
<p><strong>-async [x]</strong> (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
(<em>x</em> = “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. <em>This might in
principle be mitigated by using the <code>-al</code> 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</em>.</p>
<p><strong>-async no</strong>. 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 <code>-async</code> option set in a “uxplayrc”
configuration file.</p>
<p><strong>-s wxh</strong> (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 <strong>height</strong> 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).</p>
<p><strong>-s wxh@r</strong> 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.</p>
<p><strong>-o</strong> 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: <strong>don’t use this option</strong> unless there is
some special reason to use it.</p>
<p><strong>-fs</strong> uses fullscreen mode, but only works with X11,
Wayland or VAAPI.</p>
<p><strong>-p</strong> 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].</p>
<p>If the -p option is not used, the ports are chosen dynamically
(randomly), which will not work if a firewall is running.</p>
<p><strong>-avdec</strong> 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.</p>
<p><strong>-vp <em>parser</em></strong> choses the GStreamer pipeline’s
h264 parser element, default is h264parse. Using quotes “…” allows
options to be added.</p>
<p><strong>-vd <em>decoder</em></strong> 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.</p>
<p><strong>-vc <em>converter</em></strong> chooses the GStreamer
pipeline’s videoconverter element, instead of the default value
“videoconvert”. When using Video4Linux2 hardware-decoding by a
GPU,<code>-vc v4l2convert</code> will also use the GPU for video
conversion. Using quotes “…” allows some parameters to be included with
the converter name.</p>
<p><strong>-vs <em>videosink</em></strong> 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, <strong>fullscreen</strong> mode is
supported by the vaapisink plugin, and is obtained using
<code>-vs "vaapisink fullscreen=true"</code>; this also works with
<code>waylandsink</code>. The syntax of such options is specific to a
given plugin, and some choices of videosink might not work on your
system.</p>
<p><strong>-vs 0</strong> 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.</p>
<p><strong>-v4l2</strong> Video settings for hardware h264 video
decoding in the GPU by Video4Linux2. Equivalent to
<code>-vd v4l2h264dec -vc v4l2convert</code>.</p>
<p><strong>-bt709</strong> 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.</p>
<p><strong>-rpi</strong> Equivalent to “-v4l2”. Use for “Desktop”
Raspberry Pi systems with X11.</p>
<p><strong>-rpigl</strong> Equivalent to “-rpi -vs glimagesink”.
Sometimes better for “Desktop” Raspberry Pi systems with X11.</p>
<p><strong>-rpifb</strong> Equivalent to “-rpi -vs kmssink” (use for
Raspberry Pi systems using the framebuffer, like RPi OS Bullseye
Lite).</p>
<p><strong>-rpiwl</strong> Equivalent to “-rpi -vs waylandsink”, for
Raspberry Pi “Desktop” systems using the Wayland video compositor (use
for Ubuntu 21.10 for Raspberry Pi 4B).</p>
<p><strong>-as <em>audiosink</em></strong> 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.)</p>
<p><strong>-as 0</strong> (or just <strong>-a</strong>) suppresses
playing of streamed audio, but displays streamed video.</p>
<p><strong>-al <em>x</em></strong> specifies an audio latency <em>x</em>
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). <em>(However, the client appears to ignore this reported latency,
so this option seems non-functional.)</em></p>
<p><strong>-ca <em>filename</em></strong> provides a file (where