uxplay.1

.TH UXPLAY "1" "2025-10-26" "UxPlay 1.72" "User Commands"
.SH NAME
uxplay \- start AirPlay server
.SH SYNOPSIS
.B uxplay
[\fI\,-n name\/\fR] [\fI\,-s wxh\/\fR] [\fI\,-p \/\fR[\fI\,n\/\fR]] [more \fI OPTIONS \/\fR ...]
.SH DESCRIPTION
UxPlay 1.72: An open\-source AirPlay mirroring (+ audio streaming) server:
.SH OPTIONS
.TP
.B
\fB\-n\fR name   Specify the network name of the AirPlay server (UTF-8/ascii)
.TP
\fB\-nh\fR       Do \fBNOT\fR append "@\fIhostname\fR" at end of AirPlay server name
.TP
\fB\-h265\fR     Support h265 (4K) video (with h265 versions of h264 plugins)
.TP
\fB\-hls\fR      Support HTTP Live Streaming (currently YouTube video only)
.IP
   v = 2 or 3 (default 3) optionally selects video player version
.TP
\fB\-scrsv\fI n\fR  Screensaver override \fIn\fR:0=off 1=on during activity 2=always on.  
.TP
\fB\-pin\fI[xxxx]\fRUse a 4-digit pin code to control client access (default: no)
.IP
   without option, pin is random: optionally use fixed pin xxxx.
.TP
\fB\-reg\fI [fn]\fR Keep a register in $HOME/.uxplay.register to verify returning
.IP
   client pin-registration; (option: use file "fn" for this)
.TP
\fB\-pw\fI [pwd]\fR Require use of password "pwd" to control client access.
.IP
   (with no \fIpwd\fR, pin entry is required at \fIeach\fR connection.)

.IP
   (option "-pw" after "-pin" overrides it, and vice versa.)
.TP
\fB\-vsync\fI[x]\fR Mirror mode: sync audio to video using timestamps (default)
.IP
   \fIx\fR is optional audio delay: millisecs, decimal, can be neg.
.TP
\fB\-vsync\fR no Switch off audio/(server)video timestamp synchronization.
.TP
\fB\-async\fR[\fIx\fR] Audio-Only mode: sync audio to client video (default: no).
.TP
\fB\-async\fR no Switch off audio/(client)video timestamp synchronization.
.TP
\fB\-db\fI l[:h]\fR Set minumum volume attenuation to l dB (decibels, negative);
.IP
   optional: set maximum to h dB (+ or -); default -30.0:0.0
.PP
.TP
\fB\-taper\fR    Use a "tapered" AirPlay volume-control profile.
.TP
\fB\-vol\fI v \fR   Set initial audio-streaming volume: range [mute=0.0:1.0=full].
.TP
\fB\-s\fR wxh[@r]Request to client for video display resolution [refresh_rate]
.IP
   default 1920x1080[@60] (or 3840x2160[@60] with -h265 option).
.PP
.TP
\fB\-o\fR        Set display "overscanned" mode on (not usually needed)
.TP
\fB-fs\fR       Full-screen (only with X11, Wayland, VAAPI, D3D11, kms)
.TP
\fB\-p\fR        Use legacy ports UDP 6000:6001:7011 TCP 7000:7001:7100
.TP
\fB\-p\fR n      Use TCP and UDP ports n,n+1,n+2. range 1024\-65535
.IP
   use "\-p n1,n2,n3" to set each port, "n1,n2" for n3 = n2+1
.IP
   "\-p tcp n" or "\-p udp n" sets TCP or UDP ports separately.
.PP
.TP
\fB\-avdec\fR    Force software h264 video decoding with libav decoder.
.TP
\fB\-vp\fI prs \fR  Choose GStreamer h264 parser; default "h264parse"
.TP
\fB\-vd\fI dec \fR  Choose GStreamer h264 decoder; default "decodebin"
.IP
   choices: (software) avdec_h264; (hardware) v4l2h264dec,
.IP
   nvdec, nvh264dec, vaapih264dec, vtdec, ...
.TP
\fB\-vc\fI cnv \fR  Choose GStreamer videoconverter; default "videoconvert"
.IP
   another choice when using v4l2h264dec: v4l2convert.
.TP
\fB\-vs\fI sink\fR  Choose the GStreamer videosink; default "autovideosink"
.IP
   choices: ximagesink,xvimagesink,vaapisink,glimagesink,
.IP
   gtksink,waylandsink,kmssink,fbdevsink,osxvideosink,
.IP
   d3d11videosink,d3d12videosink ...
.PP
.TP
\fB\-vs\fR 0     Streamed audio only, with no video display window.
.TP
\fB\-vrtp\fI pl\fR  Use rtph26[4,5]pay to send decoded video elsewhere: "pl"
.IP
   is the remaining pipeline, starting with rtph26*pay options:
.IP
   e.g. "config-interval=1 ! udpsink host=127.0.0.1 port=5000"
.PP
.TP
\fB\-v4l2\fR     Use Video4Linux2 for GPU hardware h264 video decoding.
.TP
\fB\-bt709\fR    Sometimes needed for Raspberry Pi models using Video4Linux2.
.TP
\fB\-srgb\fR     Display "Full range" [0-255] color, not "Limited Range"[16-235]
.IP
   This is a workaround for a GStreamer problem, until it is fixed.
.PP
\fB\-srgb\fR no  Disable srgb option (use when enabled by default: Linux, *BSD)
.TP
\fB\-as\fI sink\fR  Choose the GStreamer audiosink; default "autoaudiosink"
.IP
   choices:pulsesink,alsasink,pipewiresink,osssink,oss4sink,
.IP
   jackaudiosink,osxaudiosink,wasapisink,directsoundsink,..
.PP
.TP
\fB\-as\fR 0     (or \fB\-a\fR) Turn audio off, streamed video only.
.TP
\fB\-al\fR x     Audio latency in seconds (default 0.25) reported to client.
.TP
\fB\-ca\fR       Display cover-art in AirPlay Audio (ALAC) mode.
.TP
\fB\-ca\fI fn \fR   In Airplay Audio (ALAC) mode, write cover-art to file fn.
.TP
\fB\-md\fI fn \fR   In Airplay Audio (ALAC) mode, write metadata text to file fn.
.TP
\fB\-reset\fR n  Reset after n seconds client silence (default n=15, 0=never).
.TP
\fB\-nofreeze\fR Do NOT leave frozen screen in place after reset.
.TP
\fB\-nc\fR       Do NOT close video window when client stops mirroring.
.TP
\fB\-nc\fR  no   Cancel the -nc option (DO close video window).
.TP
\fB\-nohold\fR   Drop current connection when new client connects.
.TP
\fB\-restrict\fR Restrict clients to those specified by "-allow deviceID".
.IP
   Uxplay displays deviceID when a client attempts to connect.
.IP
   Use "-restrict no" for no client restrictions (default).
.PP
\fB\-allow\fR id Permit deviceID = id to connect if restrictions are imposed.
.TP
\fB\-block\fR id Always block connections from deviceID = id.
.TP
\fB\-FPSdata\fR  Show video-streaming performance reports sent by client.
.TP
\fB\-fps\fR n    Set maximum allowed streaming framerate, default 30
.TP
\fB\-f\fR {H|V|I}Horizontal|Vertical flip, or both=Inversion=rotate 180 deg
.TP
\fB\-r\fR {R|L}  Rotate 90 degrees Right (cw) or Left (ccw)
.TP
\fB\-m\fI [mac]\fR  Set MAC address (also Device ID); use for concurrent UxPlays
.IP
   if mac xx:xx:xx:xx:xx:xx is not given, a random MAC is used.
.PP
.TP
\fB\-key\fI [fn]\fR Store private key in $HOME/.uxplay.pem (or in file "fn")
.PP
.TP
\fB\-dacp\fI [fn]\fRExport client DACP information to file $HOME/.uxplay.dacp
.IP
   (option to use file "fn" instead); used for client remote.
.PP
.TP
\fB\-vdmp\fR [n] Dump h264 video output to "fn.h264"; fn="videodump", change
.IP
   with "-vdmp [n] filename". If [n] is given, file fn.x.h264
.IP
   x=1,2,.. opens whenever a new SPS/PPS NAL arrives, and <=n
.IP
   NAL units are dumped.
.PP
.TP
\fB\-admp\fR [n] Dump audio output to "fn.x.fmt", fmt ={aac, alac, aud}, x
.IP
   =1,2,..; fn="audiodump"; change with "-admp [n] filename".
.IP
   x increases when audio format changes. If n is given, <= n
.IP
   audio packets are dumped. "aud"= unknown format.
.PP
.TP
\fB\-ble\fI [fn]\fR For BluetoothLE beacon: write data to default file ~/.uxplay.ble
.IP
   optional: write to file "fn" ("fn" = "off" to cancel)
.TP
\fB\-d [n]\fR    Enable debug logging; optional: n=1 to skip normal packet data.
.TP
\fB\-v\fR        Displays version information
.TP
\fB\-h\fR        Displays help information
.TP
\fB\-rc\fI fn\fR    Read startup options from file "fn" instead of ~/.uxplayrc, etc
.SH
FILES
Options in one of $UXPLAYRC, or ~/.uxplayrc, or  ~/.config/uxplayrc
.TP
are applied first (command-line options may modify them).  Format:
.TP
one option per line,\fI no\fR initial "-"; lines beginning with "#" ignored.
.SH
AUTHORS
.TP
Various, see website or distribution.
.SH
COPYRIGHT
.TP
Various, see website or distribution.  License: GPL v3+: 
.TP
GNU GPL version 3 or later. (some parts LGPL v.2.1+ or MIT).
.SH
SEE ALSO
.TP
Website: <https://github.com/FDH2/UxPlay>