mirror/Sunshine
1
0
Fork 0
mirror of https://github.com/LizardByte/Sunshine.git synced 2024-11-18 20:09:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
a1d8cc2296
Sunshine/docs/source/about/advanced_usage.rst
Conn O'Griofa 2d969c2ccc platform/windows: change dwmflush default, add autodetection 
On each re/init, query the active monitor refresh rate via
DwmGetCompositionTimingInfo. If the client requested framerate exceeds
the host monitor refresh, automatically disable DwmFlush.

This avoids the problem by which DwmFlush would constrain the client
FPS if the host monitor runs at a lower refresh rate, thus allowing
the feature to be enabled by default.

If there are other issues caused by DwmFlush for certain systems,
it can still be disabled via configuration.
2022-06-15 22:23:09 +01:00

1112 lines
21 KiB
ReStructuredText
Raw Blame History

:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/about/advanced_usage.rst
Advanced Usage
==============
Sunshine will work with the default settings for most users. In some cases you may want to configure Sunshine further.
Configuration
-------------
The default location for the configuration file is listed below. You can use another location if you
choose, by passing in the full configuration file path as the first argument when you start Sunshine.
The default location of the ``apps.json`` is the same as the configuration file. You can use a custom
location by modifying the configuration file.
**Default File Location**
.. table::
:widths: auto
======= ===========
Value Description
======= ===========
Docker /config/
Linux /usr/local/sunshine/config/
MacOS /usr/local/sunshine/config/
Windows ./config/
======= ===========
Example
.. code-block:: bash
sunshine ~/sunshine_config.conf
To manually configure sunshine you may edit the `conf` file in a text editor. Use the examples as reference.
.. Hint:: Some settings are not available within the web ui.
General
-------
sunshine_name
^^^^^^^^^^^^^
Description
The name displayed by Moonlight
Default
PC hostname
Example
.. code-block:: text
sunshine_name = Sunshine
min_log_level
^^^^^^^^^^^^^
Description
The minimum log level printed to standard out.
**Choices**
.. table::
:widths: auto
======= ===========
Value Description
======= ===========
verbose verbose logging
debug debug logging
info info logging
warning warning logging
error error logging
fatal fatal logging
none no logging
======= ===========
Default
``info``
Example
.. code-block:: text
min_log_level = info
Controls
--------
gamepad
^^^^^^^
Description
The type of gamepad to emulate on the host.
.. Caution:: Applies to Windows only.
**Choices**
.. table::
:widths: auto
===== ===========
Value Description
===== ===========
x360 xbox 360 controller
ds4 dualshock controller (PS4)
===== ===========
Default
``x360``
Example
.. code-block:: text
gamepad = x360
back_button_timeout
^^^^^^^^^^^^^^^^^^^
Description
If, after the timeout, the back/select button is still pressed down, Home/Guide button press is emulated.
On Nvidia Shield, the home and power button are not passed to Moonlight.
.. Tip:: If back_button_timeout < 0, then the Home/Guide button will not be emulated.
Default
``2000``
Example
.. code-block:: text
back_button_timeout = 2000
key_repeat_delay
^^^^^^^^^^^^^^^^
Description
The initial delay in milliseconds before repeating keys. Controls how fast keys will repeat themselves.
Default
``500``
Example
.. code-block:: text
key_repeat_delay = 500
key_repeat_frequency
^^^^^^^^^^^^^^^^^^^^
Description
How often keys repeat every second.
.. Tip:: This configurable option supports decimals.
Default
.. Todo:: Unknown
Example
.. code-block:: text
key_repeat_frequency = 24.9
keybindings
^^^^^^^^^^^
Description
Sometimes it may be useful to map keybindings. Wayland won't allow clients to capture the Win Key for example.
.. Tip:: See `virtual key codes <https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes>`_
.. Hint:: keybindings needs to have a multiple of two elements.
Default
None
Example
.. code-block:: text
keybindings = [
0x10, 0xA0,
0x11, 0xA2,
0x12, 0xA4,
0x4A, 0x4B
]
key_rightalt_to_key_win
^^^^^^^^^^^^^^^^^^^^^^^
Description
It may be possible that you cannot send the Windows Key from Moonlight directly. In those cases it may be useful to
make Sunshine think the Right Alt key is the Windows key.
Default
None
Example
.. code-block:: text
key_rightalt_to_key_win = enabled
Display
-------
adapter_name
^^^^^^^^^^^^
Description
Select the video card you want to stream.
.. Tip:: To find the name of the appropriate values follow these instructions.
Linux + VA-API
Unlike with `amdvce` and `nvenc`, it doesn't matter if video encoding is done on a different GPU.
.. code-block:: bash
ls /dev/dri/renderD* # to find all devices capable of VAAPI
# replace ``renderD129`` with the device from above to lists the name and capabilities of the device
vainfo --display drm --device /dev/dri/renderD129 | \
grep -E "((VAProfileH264High|VAProfileHEVCMain|VAProfileHEVCMain10).*VAEntrypointEncSlice)|Driver version"
To be supported by Sunshine, it needs to have at the very minimum:
``VAProfileH264High : VAEntrypointEncSlice``
.. Todo:: MacOS
Windows
.. code-block:: batch
tools\dxgi-info.exe
Default
Sunshine will select the default video card.
Examples
Linux
.. code-block:: text
adapter_name = /dev/dri/renderD128
.. Todo:: MacOS
Windows
.. code-block:: text
adapter_name = Radeon RX 580 Series
output_name
^^^^^^^^^^^
Description
Select the display number you want to stream.
.. Tip:: To find the name of the appropriate values follow these instructions.
Linux
.. code-block:: bash
xrandr --listmonitors
Example output: ``0: +HDMI-1 1920/518x1200/324+0+0 HDMI-1``
You need to use the value before the colon in the output, e.g. ``0``.
.. Todo:: MacOS
Windows
.. code-block:: batch
tools\dxgi-info.exe
Default
Sunshine will select the default display.
Examples
Linux
.. code-block:: text
output_name = 0
.. Todo:: MacOS
Windows
.. code-block:: text
output_name = \\.\DISPLAY1
fps
^^^
Description
The fps modes advertised by Sunshine.
.. Note:: Some versions of Moonlight, such as Moonlight-nx (Switch), rely on this list to ensure that the requested
fps is supported.
Default
.. Todo:: Unknown
Example
.. code-block:: text
fps = [10, 30, 60, 90, 120]
resolutions
^^^^^^^^^^^
Description
The resolutions advertised by Sunshine.
.. Note:: Some versions of Moonlight, such as Moonlight-nx (Switch), rely on this list to ensure that the requested
resolution is supported.
Default
.. Todo:: Unknown
Example
.. code-block:: text
resolutions = [
352x240,
480x360,
858x480,
1280x720,
1920x1080,
2560x1080,
3440x1440,
1920x1200,
3860x2160,
3840x1600,
]
dwmflush
^^^^^^^^
Description
Invoke DwmFlush() to sync screen capture to the Windows presentation interval.
.. Caution:: Applies to Windows only. Alleviates visual stuttering during mouse movement.
If enabled, this feature will automatically deactivate if the client framerate exceeds
the host monitor's current refresh rate.
Default
``enabled``
Examples
Windows
.. code-block:: text
dwmflush = enabled
Audio
-----
audio_sink
^^^^^^^^^^
Description
The name of the audio sink used for audio loopback.
.. Tip:: To find the name of the audio sink follow these instructions.
Linux + pulseaudio
.. code-block:: bash
pacmd list-sinks | grep "name:"
Linux + pipewire
.. code-block:: bash
pactl info | grep Source
# in some causes you'd need to use the `Sink` device, if `Source` doesn't work, so try:
pactl info | grep Sink
MacOS
Sunshine can only access microphones on MacOS due to system limitations. To stream system audio use
`Soundflower <https://github.com/mattingalls/Soundflower>`_ or
`BlackHole <https://github.com/ExistentialAudio/BlackHole>`_.
Windows
.. code-block:: batch
tools\audio-info.exe
Default
Sunshine will select the default audio device.
Examples
Linux
.. code-block:: text
audio_sink = alsa_output.pci-0000_09_00.3.analog-stereo
MacOS
.. code-block:: text
audio_sink = BlackHole 2ch
Windows
.. code-block:: text
audio_sink = {0.0.0.00000000}.{FD47D9CC-4218-4135-9CE2-0C195C87405B}
virtual_sink
^^^^^^^^^^^^
Description
The audio device that's virtual, like Steam Streaming Speakers. This allows Sunshine to stream audio, while muting
the speakers.
.. Tip:: See `audio_sink`_!
Default
.. Todo:: Unknown
Example
.. code-block:: text
virtual_sink = {0.0.0.00000000}.{8edba70c-1125-467c-b89c-15da389bc1d4}
Network
-------
external_ip
^^^^^^^^^^^
Description
If no external IP address is given, Sunshine will attempt to automatically detect external ip-address.
Default
Automatic
Example
.. code-block:: text
external_ip = 123.456.789.12
port
^^^^
Description
Set the family of ports used by Sunshine.
Default
``47989``
Example
.. code-block:: text
port = 47989
pkey
^^^^
Description
The private key. This must be 2048 bits.
Default
.. Todo:: Unknown
Example
.. code-block:: text
pkey = /dir/pkey.pem
cert
^^^^
Description
The certificate. Must be signed with a 2048 bit key.
Default
.. Todo:: Unknown
Example
.. code-block:: text
cert = /dir/cert.pem
origin_pin_allowed
^^^^^^^^^^^^^^^^^^
Description
The origin of the remote endpoint address that is not denied for HTTP method /pin.
**Choices**
.. table::
:widths: auto
===== ===========
Value Description
===== ===========
pc Only localhost may access /pin
lan Only LAN devices may access /pin
wan Anyone may access /pin
===== ===========
Default
``pc``
Example
.. code-block:: text
origin_pin_allowed = pc
origin_web_ui_allowed
^^^^^^^^^^^^^^^^^^^^^
Description
The origin of the remote endpoint address that is not denied for HTTPS Web UI.
**Choices**
.. table::
:widths: auto
===== ===========
Value Description
===== ===========
pc Only localhost may access the web ui
lan Only LAN devices may access the web ui
wan Anyone may access the web ui
===== ===========
Default
``lan``
Example
.. code-block:: text
origin_web_ui_allowed = lan
upnp
^^^^
Description
Sunshine will attempt to open ports for streaming over the internet.
**Choices**
.. table::
:widths: auto
===== ===========
Value Description
===== ===========
on enable UPnP
off disable UPnP
===== ===========
Default
``off``
Example
.. code-block:: text
upnp = on
ping_timeout
^^^^^^^^^^^^
Description
How long to wait in milliseconds for data from Moonlight before shutting down the stream.
Default
``10000``
Example
.. code-block:: text
ping_timeout = 10000
Encoding
--------
channels
^^^^^^^^
Description
This will generate distinct video streams, unlike simply broadcasting to multiple Clients.
When multicasting, it could be useful to have different configurations for each connected Client.
For instance:
- Clients connected through WAN and LAN have different bitrate constraints.
- Decoders may require different settings for color.
.. Warning:: CPU usage increases for each distinct video stream generated.
Default
``1``
Example
.. code-block:: text
channels = 1
fec_percentage
^^^^^^^^^^^^^^
Description
Percentage of error correcting packets per data packet in each video frame.
.. Warning:: Higher values can correct for more network packet loss, but at the cost of increasing bandwidth usage.
Default
``20``
Range
``1-255``
Example
.. code-block:: text
fec_percentage = 20
qp
^^
Description
Quantitization Parameter. Some devices don't support Constant Bit Rate. For those devices, QP is used instead.
.. Warning:: Higher value means more compression, but less quality.
Default
``28``
Example
.. code-block:: text
qp = 28
min_threads
^^^^^^^^^^^
Description
Minimum number of threads used by ffmpeg to encode the video.
.. Note:: Increasing the value slightly reduces encoding efficiency, but the tradeoff is usually worth it to gain
the use of more CPU cores for encoding. The ideal value is the lowest value that can reliably encode at your
desired streaming settings on your hardware.
Default
``1``
Example
.. code-block:: text
min_threads = 1
hevc_mode
^^^^^^^^^
Description
Allows the client to request HEVC Main or HEVC Main10 video streams.
.. Warning:: HEVC is more CPU-intensive to encode, so enabling this may reduce performance when using software
encoding.
**Choices**
.. table::
:widths: auto
===== ===========
Value Description
===== ===========
0 advertise support for HEVC based on encoder
1 do not advertise support for HEVC
2 advertise support for HEVC Main profile
3 advertise support for HEVC Main and Main10 (HDR) profiles
===== ===========
Default
``0``
Example
.. code-block:: text
hevc_mode = 2
encoder
^^^^^^^
Description
Force a specific encoder.
**Choices**
.. table::
:widths: auto
======== ===========
Value Description
======== ===========
nvenc For Nvidia graphics cards
amdvce For AMD graphics cards
software Encoding occurs on the CPU
======== ===========
Default
Sunshine will use the first encoder that is available.
Example
.. code-block:: text
encoder = nvenc
sw_preset
^^^^^^^^^
Description
The encoder preset to use.
.. Note:: This option only applies when using software `encoder`_.
.. Note:: From `FFmpeg <https://trac.ffmpeg.org/wiki/Encode/H.264#preset>`_.
A preset is a collection of options that will provide a certain encoding speed to compression ratio. A slower
preset will provide better compression (compression is quality per filesize). This means that, for example, if
you target a certain file size or constant bit rate, you will achieve better quality with a slower preset.
Similarly, for constant quality encoding, you will simply save bitrate by choosing a slower preset.
Use the slowest preset that you have patience for.
**Choices**
.. table::
:widths: auto
========= ===========
Value Description
========= ===========
ultrafast fastest
superfast
veryfast
superfast
faster
fast
medium
slow
slow
slower
veryslow slowest
========= ===========
Default
``superfast``
Example
.. code-block:: text
sw_preset = superfast
sw_tune
^^^^^^^
Description
The tuning preset to use.
.. Note:: This option only applies when using software `encoder`_.
.. Note:: From `FFmpeg <https://trac.ffmpeg.org/wiki/Encode/H.264#preset>`_.
You can optionally use -tune to change settings based upon the specifics of your input.
**Choices**
.. table::
:widths: auto
=========== ===========
Value Description
=========== ===========
film use for high quality movie content; lowers deblocking
animation good for cartoons; uses higher deblocking and more reference frames
grain preserves the grain structure in old, grainy film material
stillimage good for slideshow-like content
fastdecode allows faster decoding by disabling certain filters
zerolatency good for fast encoding and low-latency streaming
=========== ===========
Default
``zerolatency``
Example
.. code-block:: text
sw_tune = zerolatency
nv_preset
^^^^^^^^^
Description
The encoder preset to use.
.. Note:: This option only applies when using nvenc `encoder`_.
**Choices**
.. table::
:widths: auto
========== ===========
Value Description
========== ===========
default let ffmpeg decide
hp high performance
hq high quality
slow high quality, 2 passes
medium high quality, 1 pass
fast high performance, 1 pass
bd
ll low latency
llhq low latency, high quality
llhp low latency, high performance
lossless lossless
losslesshp lossless, high performance
========== ===========
Default
``llhq``
Example
.. code-block:: text
nv_preset = llhq
nv_rc
^^^^^
Description
The encoder rate control.
.. Note:: This option only applies when using nvenc `encoder`_.
.. Note:: Moonlight does not currently support variable bitrate, although it can still be selected here.
**Choices**
.. table::
:widths: auto
========== ===========
Value Description
========== ===========
auto let ffmpeg decide
constqp constant QP mode
cbr constant bitrate
cbr_hq constant bitrate, high quality
cbr_ld_hq constant bitrate, low delay, high quality
vbr variable bitrate
vbr_hq variable bitrate, high quality
========== ===========
Default
``auto``
Example
.. code-block:: text
nv_rc = auto
nv_coder
^^^^^^^^
Description
The entropy encoding to use.
.. Note:: This option only applies when using nvenc `encoder`_.
**Choices**
.. table::
:widths: auto
========== ===========
Value Description
========== ===========
auto let ffmpeg decide
cabac
cavlc
========== ===========
Default
``auto``
Example
.. code-block:: text
nv_coder = auto
amd_quality
^^^^^^^^^^^
Description
The encoder preset to use.
.. Note:: This option only applies when using amdvce `encoder`_.
**Choices**
.. table::
:widths: auto
========== ===========
Value Description
========== ===========
default let ffmpeg decide
speed fast
balanced balance performance and speed
========== ===========
Default
``balanced``
Example
.. code-block:: text
amd_quality = balanced
amd_rc
^^^^^^
Description
The encoder rate control.
.. Note:: This option only applies when using amdvce `encoder`_.
.. Note:: Moonlight does not currently support variable bitrate, although it can still be selected here.
**Choices**
.. table::
:widths: auto
=========== ===========
Value Description
=========== ===========
auto let ffmpeg decide
constqp constant QP mode
cbr constant bitrate
vbr_latency variable bitrate, latency constrained
vbr_peak variable bitrate, peak constrained
=========== ===========
Default
``auto``
Example
.. code-block:: text
amd_rc = auto
amd_coder
^^^^^^^^^
Description
The entropy encoding to use.
.. Note:: This option only applies when using nvenc `encoder`_.
**Choices**
.. table::
:widths: auto
========== ===========
Value Description
========== ===========
auto let ffmpeg decide
cabac
cavlc
========== ===========
Default
``auto``
Example
.. code-block:: text
amd_coder = auto
vt_software
^^^^^^^^^^^
Description
Force Video Toolbox to use software encoding.
.. Note:: This option only applies when using MacOS.
**Choices**
.. table::
:widths: auto
========== ===========
Value Description
========== ===========
auto let ffmpeg decide
disabled disable software encoding
allowed allow software encoding
forced force software encoding
========== ===========
Default
``auto``
Example
.. code-block:: text
vt_software = auto
vt_realtime
^^^^^^^^^^^
Description
Realtime encoding.
.. Note:: This option only applies when using MacOS.
.. Warning:: Disabling realtime encoding might result in a delayed frame encoding or frame drop.
Default
``enabled``
Example
.. code-block:: text
vt_realtime = enabled
vt_coder
^^^^^^^^
Description
The entropy encoding to use.
.. Note:: This option only applies when using MacOS.
**Choices**
.. table::
:widths: auto
========== ===========
Value Description
========== ===========
auto let ffmpeg decide
cabac
cavlc
========== ===========
Default
``auto``
Example
.. code-block:: text
vt_coder = auto
Advanced
--------
file_apps
^^^^^^^^^
Description
The application configuration file path. The file contains a json formatted list of applications that can be started
by Moonlight.
Default
OS and package dependent
Example
.. code-block:: text
file_apps = apps.json
file_state
^^^^^^^^^^
Description
The file where current state of Sunshine is stored.
Default
``sunshine_state.json``
Example
.. code-block:: text
file_state = sunshine_state.json
credentials_file
^^^^^^^^^^^^^^^^
Description
The file where user credentials for the UI are stored.
Default
``sunshine_state.json``
Example
.. code-block:: text
credentials_file = sunshine_state.json
Reference in New Issue View Git Blame Copy Permalink