docs/configuration.md
@admonition{ Host authority | @htmlonly By providing the host authority (URI + port), you can easily open each configuration option in the config UI.
<script src="configuration.js"></script><strong>Host authority: </strong> <input type="text" id="host-authority" value="localhost:47990"> @endhtmlonly }
Sunshine will work with the default settings for most users. In some cases you may want to configure Sunshine further.
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.
Example
sunshine ~/sunshine_config.conf
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 Config Directory
| OS | Location |
|---|---|
| Docker | @code{}/config@endcode |
| Linux | @code{}~/.config/sunshine@endcode |
| macOS | @code{}~/.config/sunshine@endcode |
| Windows | @code{}%ProgramFiles%\Sunshine\config@endcode |
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.
When disabled, motion sensors will not be taken into account during gamepad type selection.
@hint{Only applies when gamepad is set to auto.}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
enabled
@endcode</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
motion_as_ds4 = enabled
@endcode</td>
</tr>
When disabled, touchpad presence will not be taken into account during gamepad type selection.
@hint{Only applies when gamepad is set to auto.}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
enabled
@endcode</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
touchpad_as_ds4 = enabled
@endcode</td>
</tr>
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.}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
enabled
@endcode</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
always_send_scancodes = enabled
@endcode</td>
</tr>
This can be useful to disable for older applications that scroll too fast with high resolution scroll
events.
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
enabled
@endcode</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
high_resolution_scrolling = enabled
@endcode</td>
</tr>
This can be useful to disable for older applications without native pen/touch support.
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
enabled
@endcode</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
native_pen_touch = enabled
@endcode</td>
</tr>
**Linux + pulseaudio:**
@code{}
pacmd list-sinks | grep "name:"
@endcode
**Linux + pipewire:**
@code{}
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
@endcode
**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:**
Enter the following command in command prompt or PowerShell.
@code{}
%ProgramFiles%\Sunshine\tools\audio-info.exe
@endcode
If you have multiple audio devices with identical names, use the Device ID instead.
}
@attention{If you want to mute the host speakers, use
[virtual_sink](#virtual_sink) instead.}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">Sunshine will select the default audio device.</td>
</tr>
<tr>
<td>Example (Linux)</td>
<td colspan="2">@code{}
audio_sink = alsa_output.pci-0000_09_00.3.analog-stereo
@endcode</td>
</tr>
<tr>
<td>Example (macOS)</td>
<td colspan="2">@code{}
audio_sink = BlackHole 2ch
@endcode</td>
</tr>
<tr>
<td>Example (Windows)</td>
<td colspan="2">@code{}
audio_sink = Speakers (High Definition Audio Device)
@endcode</td>
</tr>
**Linux + VA-API:**
Unlike with *amdvce* and *nvenc*, it doesn't matter if video encoding is done on a different GPU.
@code{}
ls /dev/dri/renderD* # to find all devices capable of VAAPI
# replace ``renderD129`` with the device from above to list the name and capabilities of the device
vainfo --display drm --device /dev/dri/renderD129 | \
grep -E "((VAProfileH264High|VAProfileHEVCMain|VAProfileHEVCMain10).*VAEntrypointEncSlice)|Driver version"
@endcode
To be supported by Sunshine, it needs to have at the very minimum:
`VAProfileH264High : VAEntrypointEncSlice`
**Windows:**
Enter the following command in command prompt or PowerShell.
@code{}
%ProgramFiles%\Sunshine\tools\dxgi-info.exe
@endcode
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.
}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">Sunshine will select the default video card.</td>
</tr>
<tr>
<td>Example (Linux)</td>
<td colspan="2">@code{}
adapter_name = /dev/dri/renderD128
@endcode</td>
</tr>
<tr>
<td>Example (Windows)</td>
<td colspan="2">@code{}
adapter_name = Radeon RX 580 Series
@endcode</td>
</tr>
**Linux:**
During Sunshine startup, you should see the list of detected displays:
@code{}
Info: Detecting displays
Info: Detected display: DVI-D-0 (id: 0) connected: false
Info: Detected display: HDMI-0 (id: 1) connected: true
Info: Detected display: DP-0 (id: 2) connected: true
Info: Detected display: DP-1 (id: 3) connected: false
Info: Detected display: DVI-D-1 (id: 4) connected: false
@endcode
You need to use the id value inside the parenthesis, e.g. `1`.
**macOS:**
During Sunshine startup, you should see the list of detected displays:
@code{}
Info: Detecting displays
Info: Detected display: Monitor-0 (id: 3) connected: true
Info: Detected display: Monitor-1 (id: 2) connected: true
@endcode
You need to use the id value inside the parenthesis, e.g. `3`.
**Windows:**
During Sunshine startup, you should see the list of detected displays:
@code{}
Info: Currently available display devices:
[
{
"device_id": "{64243705-4020-5895-b923-adc862c3457e}",
"display_name": "",
"friendly_name": "IDD HDR",
"info": null
},
{
"device_id": "{77f67f3e-754f-5d31-af64-ee037e18100a}",
"display_name": "",
"friendly_name": "SunshineHDR",
"info": null
},
{
"device_id": "{daeac860-f4db-5208-b1f5-cf59444fb768}",
"display_name": "\\\\.\\DISPLAY1",
"friendly_name": "ROG PG279Q",
"info": {
"hdr_state": null,
"origin_point": {
"x": 0,
"y": 0
},
"primary": true,
"refresh_rate": {
"type": "rational",
"value": {
"denominator": 1000,
"numerator": 119998
}
},
"resolution": {
"height": 1440,
"width": 2560
},
"resolution_scale": {
"type": "rational",
"value": {
"denominator": 100,
"numerator": 100
}
}
}
}
]
@endcode
You need to use the `device_id` value.
}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">Sunshine will select the default display.</td>
</tr>
<tr>
<td>Example (Linux)</td>
<td colspan="2">@code{}
output_name = 0
@endcode</td>
</tr>
<tr>
<td>Example (macOS)</td>
<td colspan="2">@code{}
output_name = 3
@endcode</td>
</tr>
<tr>
<td>Example (Windows)</td>
<td colspan="2">@code{}
output_name = {daeac860-f4db-5208-b1f5-cf59444fb768}
@endcode</td>
</tr>
If the value is set to 0, the workaround is disabled (default). If the value is between 0 and 3000 milliseconds, Sunshine will turn off HDR, wait for the specified amount of time and then turn HDR on again. The recommended delay time is around 500 milliseconds in most cases.
DO NOT use this workaround unless you actually have issues with HDR as it directly impacts stream start time!
@note{This option works independently of [dd_hdr_option](#dd_hdr_option)}
@note{Applies to Windows only.}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
0
@endcode</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
dd_wa_hdr_toggle_delay = 500
@endcode</td>
</tr>
Depending on the [dd_resolution_option](#dd_resolution_option) and
[dd_refresh_rate_option](#dd_refresh_rate_option) values, the following mapping
groups are available:
<ul>
<li>`mixed` - both options are set to `auto`.</li>
<li>
`resolution_only` - only [dd_resolution_option](#dd_resolution_option) is set to `auto`.
</li>
<li>
`refresh_rate_only` - only [dd_refresh_rate_option](#dd_refresh_rate_option) is set to `auto`.
</li>
</ul>
For each of those groups, a list of fields can be configured to perform remapping:
<ul>
<li>
`requested_resolution` - resolution that needs to be matched in order to use this remapping entry.
</li>
<li>`requested_fps` - FPS that needs to be matched in order to use this remapping entry.</li>
<li>`final_resolution` - resolution value to be used if the entry was matched.</li>
<li>`final_refresh_rate` - refresh rate value to be used if the entry was matched.</li>
</ul>
If `requested_*` field is left empty, it will match <b>everything</b>.
If `final_*` field is left empty, the original value will not be remapped and either a requested, manual
or current value is used. However, at least one `final_*` must be set, otherwise the entry is considered
invalid.
@note{"Optimize game settings" must be enabled on client side for ANY entry with `resolution`
field to be considered.}
@note{First entry to be matched in the list is the one that will be used.}
@tip{`requested_resolution` and `final_resolution` can be omitted for `refresh_rate_only` group.}
@tip{`requested_fps` and `final_refresh_rate` can be omitted for `resolution_only` group.}
@note{Applies to Windows only.}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
dd_mode_remapping = {
"mixed": [],
"resolution_only": [],
"refresh_rate_only": []
}
@endcode
</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
dd_mode_remapping = {
"mixed": [
{
"requested_fps": "60",
"final_refresh_rate": "119.95",
"requested_resolution": "1920x1080",
"final_resolution": "2560x1440"
},
{
"requested_fps": "60",
"final_refresh_rate": "120",
"requested_resolution": "",
"final_resolution": ""
}
],
"resolution_only": [
{
"requested_resolution": "1920x1080",
"final_resolution": "2560x1440"
}
],
"refresh_rate_only": [
{
"requested_fps": "60",
"final_refresh_rate": "119.95"
}
]
}@endcode
</td>
</tr>
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.}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
superfast
@endcode</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
sw_preset = superfast
@endcode</td>
</tr>
<tr>
<td rowspan="9">Choices</td>
<td>ultrafast</td>
<td>fastest</td>
</tr>
<tr>
<td>superfast</td>
<td></td>
</tr>
<tr>
<td>veryfast</td>
<td></td>
</tr>
<tr>
<td>faster</td>
<td></td>
</tr>
<tr>
<td>fast</td>
<td></td>
</tr>
<tr>
<td>medium</td>
<td></td>
</tr>
<tr>
<td>slow</td>
<td></td>
</tr>
<tr>
<td>slower</td>
<td></td>
</tr>
<tr>
<td>veryslow</td>
<td>slowest</td>
</tr>
You can optionally use -tune to change settings based upon the specifics of your input.
}
</td>
</tr>
<tr>
<td>Default</td>
<td colspan="2">@code{}
zerolatency
@endcode</td>
</tr>
<tr>
<td>Example</td>
<td colspan="2">@code{}
sw_tune = zerolatency
@endcode</td>
</tr>
<tr>
<td rowspan="6">Choices</td>
<td>film</td>
<td>use for high quality movie content; lowers deblocking</td>
</tr>
<tr>
<td>animation</td>
<td>good for cartoons; uses higher deblocking and more reference frames</td>
</tr>
<tr>
<td>grain</td>
<td>preserves the grain structure in old, grainy film material</td>
</tr>
<tr>
<td>stillimage</td>
<td>good for slideshow-like content</td>
</tr>
<tr>
<td>fastdecode</td>
<td>allows faster decoding by disabling certain filters</td>
</tr>
<tr>
<td>zerolatency</td>
<td>good for fast encoding and low-latency streaming</td>
</tr>
| Previous | Next |
|---|---|
| Legal | App Examples |