: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 ``./assets/sunshine.conf``. You can use another location if you
choose, by passing in the full configuration file path as the first argument when you start Sunshine.

**Default File Location**

.. table::
   :widths: auto

   =======   ===========
   Value     Description
   =======   ===========
   Linux     ./assets/sunshine.conf
   MacOS     /opt/local/etc/sunshine.conf
   Windows   ./assets/sunshine.conf
   =======   ===========

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,
      ]

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 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
