Command-line and configuration.xml options #
BubbleUPnP Server accepts command-line options specified in:
java -jar BubbleUPnPServerLauncher.jar <options>
Some of these options have no equivalent in the web configuration interface, and the command-line or
the configuation.xml file is the only way to set them.
Most of these options can also be specified in the configuation.xml file, in the form:
<option>some value</option>
Where option is one of the option listed below, minus the heading dash
When the configuation.xml file is manually edited, BubbleUPnP Server must be restarted to take the changes into
account.
Command-line options have precedence over any value stored in the configuration.xml file.
Here is the list of command-line options:
- -allowGPUTranscoding
- Allow to use GPU accelerated transcoding if possible (Chromecast transcoding only)
- -allowWANConfigurationUI
- Allow to configure the server from the Internet (web interface)
- -binDir VAL
- for internal use
- -blastAliveInterval N
- Interval in seconds to periodically blast alive messages for UPnP devices managed by the server. Needed with some clients failing to discover these devices. Default: 0 (disabled). Minimum value: 30. Set to 0 to disable
- -dataDir VAL
- Directory were configuration, log and data files are written
- -disableAudioVideoTranscoding
- Disable all audio/video transcoding
- -disableAutoUpdate
- Disable automatic server version update check every day at 4am
- -disableChromecastSupport
- Disable Google Cast transcoding support. Use if running multiple BubbleUPnP Server instances to make Android BubbleUPnP pick up the correct server for transcoding
- -disableChromecastTranscodingDiscovery
- Disable Google Cast transcoding support advertisement on the LAN. Use for forcing local transcoding in Android BubbleUPnP
- -disableCloudFfprobe
- If a local ffprobe binary executable is not available, disable fallback to running it in the cloud (disable this if playback takes an abnormally slow time to start)
- -disableGoogleCastDiscovery
- Disable Google Cast device discovery
- -disableImageTranscoding
- Disable resizing of all images. May be necessary on memory constrained environments
- -disablePreventWindowsSleep
- On Windows, disable preventing Windows going into sleep mode while streaming
- -disableQobuzTidalFullBuffering [since 0.9-update46]
- Disable full buffering of Qobuz/TIDAL streams as fast as possible. Instead, performs buffering at the renderer’s pace. Disable only if there are Qobuz/TIDAL playback issues
- -disableUPnPPortForwarding
- disale automatic opening of http and https port on the router using UPnP if available
- -disableWindowsTrayIcon:
- On Windows, disable tray icon when BubbleUPnP Server is started in an interactive session
- -discoveryMaintenanceInterval N
- Interval in seconds to check for unresponding UPnP devices. Default: 300. Minimum value: 300. Set to 0 to disable
- -dsdMimeTypeOverride VAL
- DSD mime-type to use for all DSD tracks (.dsf, .dsd, .dff). Some renderers requires a specific DSD mime-type to accept to play it natively at all
- -enableAccessLog
- Enable logging of stream requests to file in NCSA format (access_log.txt)
- -enableGoogleCastAlbumArt
- whether to force sending album art as part of metadata when playing to Google Cast devices for which this cannot be determined automatically. Enabling this option may result in media not playing at all
- -enableStreamProxyRequestLog
- Enable logging of stream requests headers for debug purpose only
- -ffmpegDir VAL
- directory to use for ffmpeg/ffprobe binaries
- -ffprobeTimeoutSec N
- ffprobe timeout in seconds
- -GPUTranscodingMethod VAL
- GPU transcoding method to use on Windows or Linux. One of:
nvidia(Windows, Linux),intel_qsv(Windows, Linux),vaapi(Linux only). If unspecified, will use the first one in this list order that eventually works. On macOS, VideoToolbox acceleration is always used if possible - -highResAudioTranscodeConvertTo16Bit
- if transcoding high res audio is enabled (see -highResAudioTranscodeMode), convert 24-bit to 16-bit
- -highResAudioTranscodeMode N
- How to transcode high resolution audio in music tracks. 0: not transcode, 1: transcode to 44.1 or 48 kHz. 2: transcode to 88.2 or 96 kHz
- -httpPort N
- http port used for incoming connections
- -httpsPort N
- https port used for incoming connections
- -lanIp
- Network interface IP address that the server will be bound to
- -logFileMaxSize N
- Max log file size in bytes
- -logGoogleCastMessages
- Extra logging for Google Cast debugging
- -logLevel VAL
- Log level, one of: OFF, ALL, FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE
- -monitorNetworkChangesInterval N
- Interval in seconds to check for network interface changes. Default: 60. Minimum value: 60. Set to 0 to disable
- -nologfile
- Disable log output to rotated files
- -nologstdout
- Disable log output to stdout
- -streamRequestMaxIdleTimeSec N
- max idle time for stream requests. Determine how long a stream can be paused then resumed
- -thumbnailWidth N
- Thumbnail width in pixel. Default: 160
- -TLSCertificateChainFiles VAL
- Comma-separated list of certificate PEM file paths
- -TLSCertificateKeyFile VAL
- PEM file path holding the private server TLS key
- -transcodeAudioSeekable
- Transcode audio files fully before serving the stream making them seekable at the expense of more delay between tracks. Requires a powerful CPU (PC)
- -transcodeAudioSeekableMaxTrackDurationSec N
- max track duration (in seconds) for which to generate seekable transcode when this feature is enabled
- -useNumericIpInStreamURL
- Use resolved numeric IP address instead of hostname in all stream URLs. Tweak required by some devices (Samsung TV) to accept to stream via tethering
- -useSoxResampler
- Use ffmpeg’s SoX resampler (if available)
- -wanHostname VAL
- Public hostname or IP address used to build stream URLs
- -webContextPath VAL
- Root path of the web server and all generated URLs. For use with reverse proxies
- -x264preset VAL
- Preset to use for H264 video encoding. One of: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow, placebo. Default: medium
- -youtubeDlDir VAL
- Directory where the youtube-dl or yt-dlp executable can be found for performing media link extraction locally rather than in the cloud. Defaults to the install directory
Configuring a custom TLS certificate #
By default, BubbleUPnP Server uses its own self-signed TLS certificate for https access.
You can replace it by your own certificate by modifying configuration.xml. Certificate must be signed by an official certificate authority (CA), commercial or not. Self-signed certificates are not supported. The hostname (or domain wildcard) of the certificate must correspond to the hostname of the machine on which BubbleUPnP Server runs.
Use the TLSCertficateChainFiles statement to specify a comma-separated list of certificates, starting mandatorily with the server’s certificate and optionally followed by any number of intermediate certificates in correct order up to the (non-listed) root CA certificate. here’s an example pointing to apache certificates:
<TLSCertificateChainFiles>/etc/apache2/server.crt,/etc/apache2/intermediate.crt</TLSCertificateChainFiles>
Similar to Apache and other popular web servers, all certificates are text files in PEM format. Each certificate file must contain one and only one PEM certificate starting with —–BEGIN CERTIFICATE—– and ending with —–END CERTIFICATE—–. If you have a certificate file containing several of these sections concatenated, you will have to split it in as many separate files and specify them all in order in TLSCertificateChainFiles.
If you forget to list intermediate certificates, it is likely that you can load the web ui via https in a web browser (if the browser includes the missing certificate), but connecting via https in Android BubbleUPnP will likely fail.
Once the certificate chain is set, you must specify a certicate for the server’s private key using the TLSCertificateKeyFile statement. Again, here’s an example pointing to an Apache private key:
<TLSCertificateKeyFile>/etc/apache2/server.key</TLSCertificateKeyFile>
The private key certificate is in PEM format as well and starts with —–BEGIN PRIVATE KEY—–.
Make sure all certificate files have the proper filesystem permission so BubbleUPnP Server can read them. Special care must be taken for the private key certificate as it should not be world readable: on Unix it should only be readable by root (if BubbleUPnP Server is running as root), on Windows it should only be readable by the Administrator account.
Once these modifications are done, restart BubbleUPnP Server and open its web configuration via https. If it works, your certificate likely loaded properly. To verify it, check the certificate chain in the web browser using the padlock icon next to the URL. If you cannot connect via https, connect via http and look for an error in the Status tab.
Accessing BubbleUPnP Server behind a reverse proxy #
You may want to put BubbleUPnP Server behind another web server acting as a reverse proxy.
Assuming you want to access BubbleUPnP Server on http://<web server hostname>:<web server port>/bubble, edit configuration.xml and change <webContextPath>/</webContextPath> to <webContextPath>/bubble</webContextPath>.
In the reverse proxy configuration of your web server, redirect access on /bubble to http://<BubbleUPnP Server LAN ip address>:<BubbleUPnP Server port>/bubble
Finally, in Android BubbleUPnP, connect to http://<web server hostname>:<web server port>/bubble
By default the BubbleUPnP Server port http port is 58050.
You can try the same for https, in which case the port is 58051.