Advanced Usage

Sunshine will work with the default settings for most users. In some cases you may want to configure Sunshine further.

Performance Tips

.. tab:: AMD

   In Windows, enabling `Enhanced Sync` in AMD's settings may help reduce the latency by an additional frame. This
   applies to `amfenc` and `libx264`.

.. tab:: NVIDIA

   Enabling `Fast Sync` in Nvidia settings may help reduce latency.

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

Value	Description
Docker	/config/
Linux	~/.config/sunshine/
macOS	~/.config/sunshine/
Windows	%ProgramFiles%\Sunshine\config

Example

sunshine ~/sunshine_config.conf

Although it is recommended to use the configuration UI, it is possible manually configure sunshine by editing the conf file in a text editor. Use the examples as reference.

General

sunshine_name

Description

The name displayed by Moonlight

Default

PC hostname

Example

sunshine_name = Sunshine

min_log_level

Description: The minimum log level printed to standard out.

Choices

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

min_log_level = info

channels

Description

Sunshine can support multiple clients streaming simultaneously, at the cost of higher CPU and GPU usage.

Note

All connected clients share control of the same streaming session.

Warning

Some hardware encoders may have limitations that reduce performance with multiple streams.

Default

1

Example

channels = 1

global_prep_cmd

Description

A list of commands to be run before/after all applications. If any of the prep-commands fail, starting the application is aborted.

Default

[]

Example

global_prep_cmd = [{"do":"nircmd.exe setdisplay 1280 720 32 144","undo":"nircmd.exe setdisplay 2560 1440 32 144"}]

Input

controller

Description

Whether to allow controller input from the client.

Example

controller = enabled

gamepad

Description: The type of gamepad to emulate on the host.

Caution!

Applies to Windows only.

Choices

Value	Description
auto	Selected based on information from client
x360	Xbox 360 controller
ds4	DualShock 4 controller (PS4)

Default

auto

Example

gamepad = auto

ds4_back_as_touchpad_click

Description

Hint

Only applies when gamepad is set to ds4 manually. Unused in other gamepad modes.

Allow Select/Back inputs to also trigger DS4 touchpad click. Useful for clients looking to emulate touchpad click on Xinput devices.

Default

enabled

Example

ds4_back_as_touchpad_click = enabled

motion_as_ds4

Description

Hint

Only applies when gamepad is set to auto.

If a client reports that a connected gamepad has motion sensor support, emulate it on the host as a DS4 controller.

When disabled, motion sensors will not be taken into account during gamepad type selection.

Default

enabled

Example

motion_as_ds4 = enabled

touchpad_as_ds4

Description

Hint

Only applies when gamepad is set to auto.

If a client reports that a connected gamepad has a touchpad, emulate it on the host as a DS4 controller.

When disabled, touchpad presence will not be taken into account during gamepad type selection.

Default

enabled

Example

touchpad_as_ds4 = enabled

back_button_timeout

Description

If the Back/Select button is held down for the specified number of milliseconds, a Home/Guide button press is emulated.

Tip

If back_button_timeout < 0, then the Home/Guide button will not be emulated.

Default

-1

Example

back_button_timeout = 2000

keyboard

Description

Whether to allow keyboard input from the client.

Example

keyboard = enabled

key_repeat_delay

Description

The initial delay, in milliseconds, before repeating keys. Controls how fast keys will repeat themselves.

Default

500

Example

key_repeat_delay = 500

key_repeat_frequency

Description

How often keys repeat every second.

Tip

This configurable option supports decimals.

Default

24.9

Example

key_repeat_frequency = 24.9

always_send_scancodes

Description

Sending scancodes enhances compatibility with games and apps but may result in incorrect keyboard input from certain clients that aren't using a US English keyboard layout.

Enable if keyboard input is not working at all in certain applications.

Disable if keys on the client are generating the wrong input on the host.

Caution!

Applies to Windows only.

Default

enabled

Example

always_send_scancodes = enabled

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

disabled

Example

key_rightalt_to_key_win = enabled

mouse

Description

Whether to allow mouse input from the client.

Example

mouse = enabled

high_resolution_scrolling

Description

When enabled, Sunshine will pass through high resolution scroll events from Moonlight clients.

This can be useful to disable for older applications that scroll too fast with high resolution scroll events.

Default

enabled

Example

high_resolution_scrolling = enabled

native_pen_touch

Description

When enabled, Sunshine will pass through native pen/touch events from Moonlight clients.

This can be useful to disable for older applications without native pen/touch support.

Default

enabled

Example

native_pen_touch = enabled

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

Hint

keybindings needs to have a multiple of two elements.

Default

[
  0x10, 0xA0,
  0x11, 0xA2,
  0x12, 0xA4
]

Example

keybindings = [
  0x10, 0xA0,
  0x11, 0xA2,
  0x12, 0xA4,
  0x4A, 0x4B
]

Note

This option is not available in the UI. A PR would be welcome.

Audio/Video

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

pacmd list-sinks | grep "name:"

Linux + pipewire

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 or BlackHole.

Windows

tools\audio-info.exe

Tip

If you have multiple audio devices with identical names, use the Device ID instead.

Tip

If you want to mute the host speakers, use virtual_sink instead.

Default

Sunshine will select the default audio device.

Examples

Linux

audio_sink = alsa_output.pci-0000_09_00.3.analog-stereo

macOS

audio_sink = BlackHole 2ch

Windows

audio_sink = Speakers (High Definition Audio Device)

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!

Tip

These are some options for virtual sound devices.

Stream Streaming Speakers (Linux, macOS, Windows)
- Steam must be installed.
- Enable install_steam_audio_drivers or use Steam Remote Play at least once to install the drivers.
Virtual Audio Cable (macOS, Windows)

Example

virtual_sink = Steam Streaming Speakers

install_steam_audio_drivers

Description

Installs the Steam Streaming Speakers driver (if Steam is installed) to support surround sound and muting host audio.

Tip

This option is only supported on Windows.

Default

enabled

Example

install_steam_audio_drivers = enabled

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.

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

tools\dxgi-info.exe

Note

For hybrid graphics systems, DXGI reports the outputs are connected to whichever graphics adapter that the application is configured to use, so it's not a reliable indicator of how the display is physically connected.

Default

Sunshine will select the default video card.

Examples

Linux

adapter_name = /dev/dri/renderD128

.. todo:: macOS

Windows

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

During Sunshine startup, you should see the list of detected monitors:

Info: Detecting connected monitors
Info: Detected monitor 0: DVI-D-0, connected: false
Info: Detected monitor 1: HDMI-0, connected: true
Info: Detected monitor 2: DP-0, connected: true
Info: Detected monitor 3: DP-1, connected: false
Info: Detected monitor 4: DVI-D-1, connected: false

You need to use the value before the colon in the output, e.g. 1.

.. todo:: macOS

Windows

tools\dxgi-info.exe

Default

Sunshine will select the default display.

Examples

Linux

output_name = 0

.. todo:: macOS

Windows

output_name  = \\.\DISPLAY1

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

Example

resolutions = [
  352x240,
  480x360,
  858x480,
  1280x720,
  1920x1080,
  2560x1080,
  3440x1440,
  1920x1200,
  3840x2160,
  3840x1600,
]

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

[10, 30, 60, 90, 120]

Example

fps = [10, 30, 60, 90, 120]

Network

upnp

Description: Sunshine will attempt to open ports for streaming over the internet.

Choices

Value	Description
on	enable UPnP
off	disable UPnP

Default

disabled

Example

upnp = on

address_family

Description: Set the address family that Sunshine will use.

Value	Description
ipv4	IPv4 only
both	IPv4+IPv6

Default

ipv4

Example

address_family = both

port

Description: Set the family of ports used by Sunshine. Changing this value will offset other ports per the table below.

Port Description	Default Port	Difference from config port
HTTPS	47984 TCP	-5
HTTP	47989 TCP	0
Web	47990 TCP	+1
RTSP	48010 TCP	+21
Video	47998 UDP	+9
Control	47999 UDP	+10
Audio	48000 UDP	+11
Mic (unused)	48002 UDP	+13

Attention!

Custom ports may not be supported by all Moonlight clients.

Default

47989

Range

1029-65514

Example

port = 47989

origin_web_ui_allowed

Description: The origin of the remote endpoint address that is not denied for HTTPS Web UI.

Choices

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

origin_web_ui_allowed = lan

external_ip

Description

If no external IP address is given, Sunshine will attempt to automatically detect external ip-address.

Default

Automatic

Example

external_ip = 123.456.789.12

lan_encryption_mode

Description: This determines when encryption will be used when streaming over your local network.

Warning

Encryption can reduce streaming performance, particularly on less powerful hosts and clients.

Choices

Value	Description
0	encryption will not be used
1	encryption will be used if the client supports it
2	encryption is mandatory and unencrypted connections are rejected

Default

0

Example

lan_encryption_mode = 0

wan_encryption_mode

Description: This determines when encryption will be used when streaming over the Internet.

Warning

Encryption can reduce streaming performance, particularly on less powerful hosts and clients.

Choices

Value	Description
0	encryption will not be used
1	encryption will be used if the client supports it
2	encryption is mandatory and unencrypted connections are rejected

Default

1

Example

wan_encryption_mode = 1

ping_timeout

Description

How long to wait, in milliseconds, for data from Moonlight before shutting down the stream.

Default

10000

Example

ping_timeout = 10000

Config Files

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

file_apps = apps.json

credentials_file

Description

The file where user credentials for the UI are stored.

Default

sunshine_state.json

Example

credentials_file = sunshine_state.json

log_path

Description

The path where the sunshine log is stored.

Default

sunshine.log

Example

log_path = sunshine.log

pkey

Description

The private key used for the web UI and Moonlight client pairing. For best compatibility, this should be an RSA-2048 private key.

Warning

Not all Moonlight clients support ECDSA keys or RSA key lengths other than 2048 bits.

Default

credentials/cakey.pem

Example

pkey = /dir/pkey.pem

cert

Description

The certificate used for the web UI and Moonlight client pairing. For best compatibility, this should have an RSA-2048 public key.

Warning

Not all Moonlight clients support ECDSA keys or RSA key lengths other than 2048 bits.

Default

credentials/cacert.pem

Example

cert = /dir/cert.pem

file_state

Description

The file where current state of Sunshine is stored.

Default

sunshine_state.json

Example

file_state = sunshine_state.json

Advanced

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

fec_percentage = 20

qp

Description

Quantization 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

qp = 28

min_threads

Description

Minimum number of CPU threads used for encoding.

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

2

Example

min_threads = 2

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

Value	Description
0	advertise support for HEVC based on encoder capabilities (recommended)
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

hevc_mode = 2

av1_mode

Description: Allows the client to request AV1 Main 8-bit or 10-bit video streams.

Warning

AV1 is more CPU-intensive to encode, so enabling this may reduce performance when using software encoding.

Choices

Value	Description
0	advertise support for AV1 based on encoder capabilities (recommended)
1	do not advertise support for AV1
2	advertise support for AV1 Main 8-bit profile
3	advertise support for AV1 Main 8-bit and 10-bit (HDR) profiles

Default

0

Example

av1_mode = 2

capture

Description: Force specific screen capture method.

Caution!

Applies to Linux only.

Choices

Value	Description
nvfbc	Use NVIDIA Frame Buffer Capture to capture direct to GPU memory. This is usually the fastest method for NVIDIA cards. For GeForce cards it will only work with drivers patched with nvidia-patch or nvlax.
wlr	Capture for wlroots based Wayland compositors via DMA-BUF.
kms	DRM/KMS screen capture from the kernel. This requires that sunshine has cap_sys_admin capability. See :ref:`Linux Setup <about/setup:install>`.
x11	Uses XCB. This is the slowest and most CPU intensive so should be avoided if possible.

Default

Automatic. Sunshine will use the first capture method available in the order of the table above.

Example

capture = kms

encoder

Description: Force a specific encoder.

Choices

Value	Description
nvenc	For NVIDIA graphics cards
quicksync	For Intel graphics cards
amdvce	For AMD graphics cards
software	Encoding occurs on the CPU

Default

Sunshine will use the first encoder that is available.

Example

encoder = nvenc

NVIDIA NVENC Encoder

nvenc_preset

Description: NVENC encoder performance preset. Higher numbers improve compression (quality at given bitrate) at the cost of increased encoding latency. Recommended to change only when limited by network or decoder, otherwise similar effect can be accomplished by increasing bitrate.

Note

This option only applies when using NVENC encoder.

Choices

Value	Description
1	P1 (fastest)
2	P2
3	P3
4	P4
5	P5
6	P6
7	P7 (slowest)

Default

1

Example

nvenc_preset = 1

nvenc_twopass

Description: Enable two-pass mode in NVENC encoder. This allows to detect more motion vectors, better distribute bitrate across the frame and more strictly adhere to bitrate limits. Disabling it is not recommended since this can lead to occasional bitrate overshoot and subsequent packet loss.

Note

This option only applies when using NVENC encoder.

Choices

Value	Description
disabled	One pass (fastest)
quarter_res	Two passes, first pass at quarter resolution (faster)
full_res	Two passes, first pass at full resolution (slower)

Default

quarter_res

Example

nvenc_twopass = quarter_res

nvenc_spatial_aq

Description: Assign higher QP values to flat regions of the video. Recommended to enable when streaming at lower bitrates.

Note

This option only applies when using NVENC encoder.

Choices

Value	Description
disabled	Don't enable Spatial AQ (faster)
enabled	Enable Spatial AQ (slower)

Default

disabled

Example

nvenc_spatial_aq = disabled

nvenc_vbv_increase

Description

Single-frame VBV/HRD percentage increase. By default sunshine uses single-frame VBV/HRD, which means any encoded video frame size is not expected to exceed requested bitrate divided by requested frame rate. Relaxing this restriction can be beneficial and act as low-latency variable bitrate, but may also lead to packet loss if the network doesn't have buffer headroom to handle bitrate spikes. Maximum accepted value is 400, which corresponds to 5x increased encoded video frame upper size limit.

Note

This option only applies when using NVENC encoder.

Warning

Can lead to network packet loss.

Default

0

Range

0-400

Example

nvenc_vbv_increase = 0

nvenc_realtime_hags

Description: Use realtime gpu scheduling priority in NVENC when hardware accelerated gpu scheduling (HAGS) is enabled in Windows. Currently NVIDIA drivers may freeze in encoder when HAGS is enabled, realtime priority is used and VRAM utilization is close to maximum. Disabling this option lowers the priority to high, sidestepping the freeze at the cost of reduced capture performance when the GPU is heavily loaded.

Note

This option only applies when using NVENC encoder.

Caution!

Applies to Windows only.

Choices

Value	Description
disabled	Use high priority
enabled	Use realtime priority

Default

enabled

Example

nvenc_realtime_hags = enabled

nvenc_latency_over_power

Description: Adaptive P-State algorithm which NVIDIA drivers employ doesn't work well with low latency streaming, so sunshine requests high power mode explicitly.

Note

This option only applies when using NVENC encoder.

Warning

Disabling it is not recommended since this can lead to significantly increased encoding latency.

Caution!

Applies to Windows only.

Choices

Value	Description
disabled	Sunshine doesn't change GPU power preferences (not recommended)
enabled	Sunshine requests high power mode explicitly

Default

enabled

Example

nvenc_latency_over_power = enabled

nvenc_opengl_vulkan_on_dxgi

Description: Sunshine can't capture fullscreen OpenGL and Vulkan programs at full frame rate unless they present on top of DXGI. This is system-wide setting that is reverted on sunshine program exit.

Note

This option only applies when using NVENC encoder.

Caution!

Applies to Windows only.

Choices

Value	Description
disabled	Sunshine leaves global Vulkan/OpenGL present method unchanged
enabled	Sunshine changes global Vulkan/OpenGL present method to "Prefer layered on DXGI Swapchain"

Default

enabled

Example

nvenc_opengl_vulkan_on_dxgi = enabled

nvenc_h264_cavlc

Description: Prefer CAVLC entropy coding over CABAC in H.264 when using NVENC. CAVLC is outdated and needs around 10% more bitrate for same quality, but provides slightly faster decoding when using software decoder.

Note

This option only applies when using H.264 format with NVENC encoder.

Choices

Value	Description
disabled	Prefer CABAC
enabled	Prefer CAVLC

Default

disabled

Example

nvenc_h264_cavlc = disabled

Intel QuickSync Encoder

qsv_preset

Description: The encoder preset to use.

Note

This option only applies when using quicksync encoder.

Choices

Value	Description
veryfast	fastest (lowest quality)
faster	faster (lower quality)
fast	fast (low quality)
medium	medium (default)
slow	slow (good quality)
slower	slower (better quality)
veryslow	slowest (best quality)

Default

medium

Example

qsv_preset = medium

qsv_coder

Description: The entropy encoding to use.

Note

This option only applies when using H264 with quicksync encoder.

Choices

Value	Description
auto	let ffmpeg decide
cabac	context adaptive binary arithmetic coding - higher quality
cavlc	context adaptive variable-length coding - faster decode

Default

auto

Example

qsv_coder = auto

qsv_slow_hevc

Description

This options enables use of HEVC on older Intel GPUs that only support low power encoding for H.264.

Caution!

Streaming performance may be significantly reduced when this option is enabled.

Default

disabled

Example

qsv_slow_hevc = disabled

AMD AMF Encoder

amd_quality

Description: The encoder preset to use.

Note

This option only applies when using amdvce encoder.

Choices

Value	Description
speed	prefer speed
balanced	balanced
quality	prefer quality

Default

balanced

Example

amd_quality = balanced

amd_rc

Description: The encoder rate control.

Note

This option only applies when using amdvce encoder.

Choices

Value	Description
cqp	constant qp mode
cbr	constant bitrate
vbr_latency	variable bitrate, latency constrained
vbr_peak	variable bitrate, peak constrained

Default

vbr_latency

Example

amd_rc = vbr_latency

amd_usage

Description: The encoder usage profile, used to balance latency with encoding quality.

Note

This option only applies when using amdvce encoder.

Choices

Value	Description
transcoding	transcoding (slowest)
webcam	webcam (slow)
lowlatency	low latency (fast)
ultralowlatency	ultra low latency (fastest)

Default

ultralowlatency

Example

amd_usage = ultralowlatency

amd_preanalysis

Description

Preanalysis can increase encoding quality at the cost of latency.

Note

This option only applies when using amdvce encoder.

Default

disabled

Example

amd_preanalysis = disabled

amd_vbaq

Description

Variance Based Adaptive Quantization (VBAQ) can increase subjective visual quality.

Note

This option only applies when using amdvce encoder.

Default

enabled

Example

amd_vbaq = enabled

amd_coder

Description: The entropy encoding to use.

Note

This option only applies when using H264 with amdvce encoder.

Choices

Value	Description
auto	let ffmpeg decide
cabac	context adaptive variable-length coding - higher quality
cavlc	context adaptive binary arithmetic coding - faster decode

Default

auto

Example

amd_coder = auto

VideoToolbox Encoder

vt_coder

Description: The entropy encoding to use.

Note

This option only applies when using macOS.

Choices

Value	Description
auto	let ffmpeg decide
cabac
cavlc

Default

auto

Example

vt_coder = auto

vt_software

Description: Force Video Toolbox to use software encoding.

Note

This option only applies when using macOS.

Choices

Value	Description
auto	let ffmpeg decide
disabled	disable software encoding
allowed	allow software encoding
forced	force software encoding

Default

auto

Example

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

vt_realtime = enabled

Software Encoder

sw_preset

Description: The encoder preset to use.

Note

This option only applies when using software encoder.

Note

From FFmpeg.

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

Value	Description
ultrafast	fastest
superfast
veryfast
faster
fast
medium
slow
slower
veryslow	slowest

Default

superfast

Example

sw_preset = superfast

sw_tune

Description: The tuning preset to use.

Note

This option only applies when using software encoder.

Note

From FFmpeg.

You can optionally use -tune to change settings based upon the specifics of your input.

Choices

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

sw_tune = zerolatency

Files

advanced_usage.rst

Latest commit

History

advanced_usage.rst

File metadata and controls

Advanced Usage

Performance Tips

Configuration

keybindings