Skip to content

configuration.md

Latest commit

 

History

History
3898 lines (3637 loc) · 109 KB

configuration.md

File metadata and controls

3898 lines (3637 loc) · 109 KB
Raw

Configuration

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

Host authority: @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.

General

locale

Description The locale used for Sunshine's user interface.
Default @code{} en @endcode
Example @code{} locale = en @endcode
Choices bg Bulgarian
cs Czech
de German
en English
en_GB English (UK)
en_US English (United States)
es Spanish
fr French
it Italian
ja Japanese
ko Korean
pl Polish
pt Portuguese
pt_BR Portuguese (Brazilian)
ru Russian
sv Swedish
tr Turkish
uk Ukranian
zh Chinese (Simplified)
zh_TW Chinese (Traditional)

sunshine_name

Description The name displayed by Moonlight.
Default PC hostname
Example @code{} sunshine_name = Sunshine @endcode

min_log_level

Description The minimum log level printed to standard out.
Default @code{} info @endcode
Example @code{} min_log_level = info @endcode
Choices verbose All logging message. @attention{This may negatively affect streaming performance.}
debug Debug log messages and higher. @attention{This may negatively affect streaming performance.}
info Informational log messages and higher.
warning Warning log messages and higher.
error Error log messages and higher.
fatal Only fatal log messages.
none No log messages.

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 @code{} [] @endcode
Example @code{} global_prep_cmd = [{"do":"nircmd.exe setdisplay 1280 720 32 144","elevated":true,"undo":"nircmd.exe setdisplay 2560 1440 32 144"}] @endcode

global_state_cmd

Description A list of commands to be run when a session resumes or pauses, for every application. The `do` commands run when the first client connects while no other client is connected, including the first connection after an app is launched. The `undo` commands run when the last client disconnects while the app keeps running.

The commands run in order on a separate thread, and the list stops at the first command that fails. They receive the same environment variables as the app, with `APOLLO_APP_STATUS` set to `RESUMING` or `PAUSING`. The `undo` commands are not run when the app is terminated, or when the app is set to terminate on pause.

An app can opt out of these commands with `exclude-global-state-cmd` and add its own with `state-cmd` in `apps.json`. @warning{These commands run on the host, and with `"elevated": true` they run elevated. Anyone who can change the configuration can run commands on the host this way.}
Default @code{} [] @endcode
Example @code{} global_state_cmd = [{"do":"cmd /C echo resumed","elevated":false,"undo":"cmd /C echo paused"}] @endcode

notify_pre_releases

Description Whether to be notified of new pre-release versions of Sunshine.
Default @code{} disabled @endcode
Example @code{} notify_pre_releases = disabled @endcode

system_tray

Description Show icon in system tray and display desktop notifications
Default @code{} enabled @endcode
Example @code{} system_tray = enabled @endcode

hide_tray_controls

Description Hide the control entries in the system tray menu, so that it only offers to open the web UI. The hidden entries are the force stop entry for the running app, "Reset Display Device Config" (Windows only), "Restart" and "Quit". @note{The tray menu is built at startup, so a change takes effect after a restart. This only changes the tray menu. The same actions remain available elsewhere, for example in the web UI.}
Default @code{} disabled @endcode
Example @code{} hide_tray_controls = enabled @endcode

enable_pairing

Description Whether new Moonlight clients may pair with this host. When disabled, every pairing request is refused with status 403 ("Pairing is disabled for this instance"), including requests that use a PIN or an OTP. @note{Clients that are already paired are not affected and can still connect. To remove a client, unpair it in the web UI.}
Default @code{} enabled @endcode
Example @code{} enable_pairing = disabled @endcode

enable_discovery

Description Whether to advertise this host on the local network with mDNS, so that clients find it automatically. When disabled, the host is not advertised and clients must add it by its IP address or host name. @warning{This only stops the host from being advertised. It does not block connections or pairing. Use [enable_pairing](#enable_pairing) to stop new clients from pairing.}
Default @code{} enabled @endcode
Example @code{} enable_discovery = disabled @endcode

Input

controller

Description Whether to allow controller input from the client.
Default @code{} enabled @endcode
Example @code{} controller = enabled @endcode

gamepad

Description The type of gamepad to emulate on the host.
Default @code{} auto @endcode
Example @code{} gamepad = auto @endcode
Choices ds4 DualShock 4 controller (PS4) @note{This option applies to Windows only.}
ds5 DualShock 5 controller (PS5) @note{This option applies to Linux only.}
switch Switch Pro controller @note{This option applies to Linux only.}
x360 Xbox 360 controller @note{This option applies to Windows only.}
xone Xbox One controller @note{This option applies to Linux only.}

ds4_back_as_touchpad_click

Description Allow Select/Back inputs to also trigger DS4 touchpad click. Useful for clients looking to emulate touchpad click on Xinput devices. @hint{Only applies when gamepad is set to ds4 manually. Unused in other gamepad modes.}
Default @code{} enabled @endcode
Example @code{} ds4_back_as_touchpad_click = enabled @endcode

motion_as_ds4

Description 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. @hint{Only applies when gamepad is set to auto.}
Default @code{} enabled @endcode
Example @code{} motion_as_ds4 = enabled @endcode

touchpad_as_ds4

Description 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. @hint{Only applies when gamepad is set to auto.}
Default @code{} enabled @endcode
Example @code{} touchpad_as_ds4 = enabled @endcode

ds5_inputtino_randomize_mac

Description Randomize the MAC-Address for the generated virtual controller. @hint{Only applies on linux for gamepads created as PS5-style controllers}
Default @code{} enabled @endcode
Example @code{} ds5_inputtino_randomize_mac = enabled @endcode

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 @code{} -1 @endcode
Example @code{} back_button_timeout = 2000 @endcode

keyboard

Description Whether to allow keyboard input from the client.
Default @code{} enabled @endcode
Example @code{} keyboard = enabled @endcode

key_repeat_delay

Description The initial delay, in milliseconds, before repeating keys. Controls how fast keys will repeat themselves.
Default @code{} 500 @endcode
Example @code{} key_repeat_delay = 500 @endcode

key_repeat_frequency

Description How often keys repeat every second. @tip{This configurable option supports decimals.}
Default @code{} 24.9 @endcode
Example @code{} key_repeat_frequency = 24.9 @endcode

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 @code{} enabled @endcode
Example @code{} always_send_scancodes = enabled @endcode

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 @code{} disabled @endcode
Example @code{} key_rightalt_to_key_win = enabled @endcode

mouse

Description Whether to allow mouse input from the client.
Default @code{} enabled @endcode
Example @code{} mouse = enabled @endcode

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 @code{} enabled @endcode
Example @code{} high_resolution_scrolling = enabled @endcode

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 @code{} enabled @endcode
Example @code{} native_pen_touch = enabled @endcode

enable_input_only_mode

Description Add a "Remote Input" entry to the app list. While another app is running, a "Terminate" entry is also shown. A "Remote Input" session sends input to the host but receives no video or audio. This is useful for controlling the desktop from a phone while it is shown on a TV, or for connecting peripherals the TV does not support.

While an app other than "Remote Input" is running, the app list shows only that app, "Remote Input" and "Terminate", and the only way to resume it is to launch the same app again. "Terminate" stops the running app. A "Remote Input" session ends when its last client disconnects. @note{While an app is running, a paired client that has only the view permission may start a "Remote Input" session, in the same way it may join the running app. Such a client can only send the input types its own input permissions allow.}
Default @code{} disabled @endcode
Example @code{} enable_input_only_mode = enabled @endcode

forward_rumble

Description Whether to forward rumble (force feedback) from games on the host to the client's gamepad. When disabled, rumble requests from the virtual gamepads are ignored. @note{Applies to Windows only.}
Default @code{} enabled @endcode
Example @code{} forward_rumble = disabled @endcode

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.} @note{This option is not available in the UI. A PR would be welcome.}
Default @code{} [ 0x10, 0xA0, 0x11, 0xA2, 0x12, 0xA4 ] @endcode
Example @code{} keybindings = [ 0x10, 0xA0, 0x11, 0xA2, 0x12, 0xA4, 0x4A, 0x4B ] @endcode

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:**
@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.}
Default Sunshine will select the default audio device.
Example (Linux) @code{} audio_sink = alsa_output.pci-0000_09_00.3.analog-stereo @endcode
Example (macOS) @code{} audio_sink = BlackHole 2ch @endcode
Example (Windows) @code{} audio_sink = Speakers (High Definition Audio Device) @endcode

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](#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](#install_steam_audio_drivers) or use Steam Remote Play at least once to install the drivers. * [Virtual Audio Cable](https://vb-audio.com/Cable) (macOS, Windows) }
Default n/a
Example @code{} virtual_sink = Steam Streaming Speakers @endcode

mic_backend

Description Select how Apollo exposes redirected client microphone audio on Windows. In this fork, Windows microphone redirection is standardized on the `steam_streaming_microphone` backend. Apollo renders decoded client microphone audio into the Steam playback endpoint, and host applications should select the paired `Microphone (Steam Streaming Microphone)` recording device. @note{This option is currently only used on Windows hosts.}
Default @code{} steam_streaming_microphone @endcode
Example @code{} mic_backend = steam_streaming_microphone @endcode

mic_device

Description The host-side device used for redirected client microphone audio. On Windows, Apollo currently auto-detects the Steam Streaming Microphone render endpoint and this value is typically left unset. On Linux and macOS this should point at the virtual device Apollo writes into.
Default Unset.
Example (Linux) @code{} mic_device = sunshine-mic @endcode

stream_audio

Description Whether to stream audio or not. Disabling this can be useful for streaming headless displays as second monitors.
Default @code{} enabled @endcode
Example @code{} stream_audio = disabled @endcode

stream_mic

Description Whether Apollo should accept redirected client microphone audio and inject it into a host-side microphone backend.
Default @code{} disabled @endcode
Example @code{} stream_mic = enabled @endcode

second_video_stream

Description Offer a client a second video stream in the same session. The client asks for it, and the second stream is either one window of this host, picked by its title, or a whole display that the host makes for it. Windows Graphics Capture takes the window. The display is a SudoVDA virtual display, made when the second stream starts and removed when it ends.

A window works anywhere the first stream does, including a MultiSeat seat. A whole display needs the console session: the host offers it only when the SudoVDA driver works and the session is not a remote (RDP) session, so a seat gets one stream when a client asks for a display. A client that does not ask is not affected. @note{Needs a client that supports it, such as MoonlightVibe.}
Default @code{} disabled @endcode
Example @code{} second_video_stream = enabled @endcode

capture_window

Description Stream one window of this host as the main picture, instead of a display. The window is matched by its title, ignoring case. An exact match wins over a partial one. Windows only. The second video stream names its own window and does not use this setting.
Default @code{} (empty, stream a display) @endcode
Example @code{} capture_window = Notepad @endcode

capture_window_wait_timeout

Description How many seconds to wait for a captured window to come back after it has gone, before the stream ends. 0 waits forever, which leaves the client on its last picture. Applies to every window stream.
Default @code{} 10 @endcode
Example @code{} capture_window_wait_timeout = 30 @endcode

capture_window_raise

Description Bring the captured window to the front when a window stream starts, so the input from the client reaches it and not a window covering it.
Default @code{} enabled @endcode
Example @code{} capture_window_raise = disabled @endcode

install_steam_audio_drivers

Description Installs the Steam Streaming Speakers driver (if Steam is installed) to support surround sound and muting host audio. @note{This option is only supported on Windows.}
Default @code{} enabled @endcode
Example @code{} install_steam_audio_drivers = enabled @endcode

keep_sink_default

Description Whether to keep the virtual sink as the default audio device while it is in use. This applies when audio is captured from a virtual sink, for example when the client has host audio playback turned off. If another program or the user changes the default audio device during the stream, it is set back to the virtual sink. @note{This option is only supported on Windows.}
Default @code{} enabled @endcode
Example @code{} keep_sink_default = disabled @endcode

auto_capture_sink

Description Whether to restart audio capture when the audio device changes during a stream, for example when the default audio device changes or the captured device is removed. When enabled, capture is set up again and picks up the new device. When disabled, capture is not set up again.
Default @code{} enabled @endcode
Example @code{} auto_capture_sink = disabled @endcode

adapter_name

Description Select the video card you want to stream. @tip{To find 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{} 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. }
Default Sunshine will select the default video card.
Example (Linux) @code{} adapter_name = /dev/dri/renderD128 @endcode
Example (Windows) @code{} adapter_name = Radeon RX 580 Series @endcode

output_name

Description Select the display number you want to stream. @tip{To find the appropriate values follow these instructions.

**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. }
Default Sunshine will select the default display.
Example (Linux) @code{} output_name = 0 @endcode
Example (macOS) @code{} output_name = 3 @endcode
Example (Windows) @code{} output_name = {daeac860-f4db-5208-b1f5-cf59444fb768} @endcode

dd_configuration_option

Description Perform mandatory verification and additional configuration for the display device. @note{Applies to Windows only.}
Default @code{} disabled @endcode
Example @code{} dd_configuration_option = ensure_only_display @endcode
Choices disabled Perform no additional configuration (disables all `dd_` configuration options).
verify_only Verify that display is active only (this is a mandatory step without any extra steps to verify display state).
ensure_active Activate the display if it's currently inactive.
ensure_primary Activate the display if it's currently inactive and make it primary.
ensure_only_display Activate the display if it's currently inactive and disable all others.

dd_resolution_option

Description Perform additional resolution configuration for the display device. @note{"Optimize game settings" must be enabled in Moonlight for this option to work.} @note{Applies to Windows only.}
Default @code{}auto@endcode
Example @code{} dd_resolution_option = manual @endcode
Choices disabled Perform no additional configuration.
auto Change resolution to the requested resolution from the client.
manual Change resolution to the user specified one (set via [dd_manual_resolution](#dd_manual_resolution)).

dd_manual_resolution

Description Specify manual resolution to be used. @note{[dd_resolution_option](#dd_resolution_option) must be set to `manual`} @note{Applies to Windows only.}
Default n/a
Example @code{} dd_manual_resolution = 1920x1080 @endcode

dd_refresh_rate_option

Description Perform additional refresh rate configuration for the display device. @note{Applies to Windows only.}
Default @code{}auto@endcode
Example @code{} dd_refresh_rate_option = manual @endcode
Choices disabled Perform no additional configuration.
auto Change refresh rate to the requested FPS value from the client.
manual Change refresh rate to the user specified one (set via [dd_manual_refresh_rate](#dd_manual_refresh_rate)).

dd_manual_refresh_rate

Description Specify manual refresh rate to be used. @note{[dd_refresh_rate_option](#dd_refresh_rate_option) must be set to `manual`} @note{Applies to Windows only.}
Default n/a
Example @code{} dd_manual_resolution = 120 dd_manual_resolution = 59.95 @endcode

dd_hdr_option

Description Perform additional HDR configuration for the display device. @note{Applies to Windows only.}
Default @code{}auto@endcode
Example @code{} dd_hdr_option = disabled @endcode
Choices disabled Perform no additional configuration.
auto Change HDR to the requested state from the client if the display supports it.

dd_wa_hdr_toggle_delay

Description When using virtual display device (VDD) for streaming, it might incorrectly display HDR color. Sunshine can try to mitigate this issue, by turning HDR off and then on again.
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.}
Default @code{} 0 @endcode
Example @code{} dd_wa_hdr_toggle_delay = 500 @endcode

dd_config_revert_delay

Description Additional delay in milliseconds to wait before reverting configuration when the app has been closed or the last session terminated. Main purpose is to provide a smoother transition when quickly switching between apps. @note{Applies to Windows only.}
Default @code{}3000@endcode
Example @code{} dd_config_revert_delay = 1500 @endcode

dd_config_revert_on_disconnect

Description When enabled, display configuration is reverted upon disconnect of all clients instead of app close or last session termination. This can be useful for returning to physical usage of the host machine without closing the active app. @warning{Some applications may not function properly when display configuration is changed while active.} @note{Applies to Windows only.}
Default @code{}disabled@endcode
Example @code{} dd_config_revert_on_disconnect = enabled @endcode

dd_mode_remapping

Description Remap the requested resolution and FPS to another display mode.
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:
  • `mixed` - both options are set to `auto`.
  • `resolution_only` - only [dd_resolution_option](#dd_resolution_option) is set to `auto`.
  • `refresh_rate_only` - only [dd_refresh_rate_option](#dd_refresh_rate_option) is set to `auto`.
For each of those groups, a list of fields can be configured to perform remapping:
  • `requested_resolution` - resolution that needs to be matched in order to use this remapping entry.
  • `requested_fps` - FPS that needs to be matched in order to use this remapping entry.
  • `final_resolution` - resolution value to be used if the entry was matched.
  • `final_refresh_rate` - refresh rate value to be used if the entry was matched.
If `requested_*` field is left empty, it will match everything.
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.}
Default @code{} dd_mode_remapping = { "mixed": [], "resolution_only": [], "refresh_rate_only": [] } @endcode
Example @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

fallback_mode

Description The display mode to use when the client does not request one, for example when an app is launched from the web UI. The format is `[Width]x[Height]x[FPS]`. The frame rate may have decimals, such as `59.94`. If the value cannot be parsed, 1920x1080 at 60 FPS is used. Always give all three parts; a two-part value such as `2560x1440` is not handled. @note{A display mode set for a specific client in the web UI takes precedence over both the client's request and this option.}
Default @code{} 1920x1080x60 @endcode
Example @code{} fallback_mode = 2560x1440x120 @endcode

headless_mode

Description Create a virtual display for every app launch, even when the client and the app do not ask for one. If the SudoVDA virtual display driver is not working, a warning is logged and the existing display is captured instead. @note{Applies to Windows only.} @note{A virtual display is also created without this option when no active display is found.}
Default @code{} disabled @endcode
Example @code{} headless_mode = enabled @endcode

double_refreshrate

Description Create virtual displays at twice the requested refresh rate. The stream itself keeps the requested frame rate. Some users report that this reduces stutter. @note{Applies to Windows only, and only when a virtual display is created.}
Default @code{} disabled @endcode
Example @code{} double_refreshrate = enabled @endcode

max_bitrate

Description The maximum bitrate (in Kbps) that Sunshine will encode the stream at. If set to 0, it will always use the bitrate requested by Moonlight.
Default @code{} 0 @endcode
Example @code{} max_bitrate = 5000 @endcode

minimum_fps_target

Description Sunshine tries to save bandwidth when content on screen is static or a low framerate. Because many clients expect a constant stream of video frames, a certain amount of duplicate frames are sent when this happens. This setting controls the lowest effective framerate a stream can reach.
Default @code{} 0 @endcode
Choices 0 Use half the stream's FPS as the minimum target.
1-1000 Specify your own value. The real minimum may differ from this value.

isolated_virtual_display_option

Description Isolates the virtual display. @note{Applies to Windows only.}
Default @code{}disabled@endcode
enabled Change the position of the virtual display (and other displays if there is a hole)

Network

upnp

Description Sunshine will attempt to open ports for streaming over the internet.
Default @code{} disabled @endcode
Example @code{} upnp = enabled @endcode

address_family

Description Set the address family that Sunshine will use.
Default @code{} ipv4 @endcode
Example @code{} address_family = both @endcode
Choices ipv4 IPv4 only
both IPv4+IPv6

port

Description Set the family of ports used by Sunshine. Changing this value will offset other ports as shown in config UI.
Default @code{} 47989 @endcode
Range 1029-65514
Example @code{} port = 47989 @endcode

origin_web_ui_allowed

Description The origin of the remote endpoint address that is not denied for HTTPS Web UI.
Default @code{} lan @endcode
Example @code{} origin_web_ui_allowed = lan @endcode
Choices pc Only localhost may access the web ui
lan Only LAN devices may access the web ui
wan Anyone may access the web ui

external_ip

Description If no external IP address is given, Sunshine will attempt to automatically detect external ip-address.
Default Automatic
Example @code{} external_ip = 123.456.789.12 @endcode

wol_mac

Description The MAC address reported to paired clients for Wake-on-LAN. If empty, the MAC address of the network adapter that serves the connection is reported. @tip{Set this only if that adapter cannot wake the machine and a different adapter handles Wake-on-LAN. Otherwise clients send wake packets to an adapter that ignores them.}
Default n/a
Example @code{} wol_mac = AA:BB:CC:DD:EE:FF @endcode

usb_forwarding_enabled

Description Let a paired client share one of its USB devices with this host through a TLS tunnel. This is the setting at startup. The tunnel only runs when it is on, and a client must also have the USB forwarding permission before it is offered. The usbip-win2 driver must be installed on this host (Windows only). Changing it takes effect after a restart. With `usb_forwarding_control` enabled, a local administrator can also start or stop the tunnel while Apollo runs; that change lasts only until Apollo restarts. Each forward is checked again every few seconds, and at once when a client is unpaired or loses the permission, so a device is detached soon after access is withdrawn. Connections that have not finished TLS get a short deadline and a small, per-address budget, separate from working forwards. @warning{Allowing a client the USB forwarding permission is equivalent to giving it physical USB access to this host. A forwarded keyboard or mouse bypasses the input permissions, and a forwarded drive is visible to every Windows session on the machine. The usbip-win2 driver is machine-wide, and any local user can detach devices through it.} @note{The local attach connection is only accepted from the System process (the usbip-win2 kernel client). That means "a kernel-mode TCP client", not specifically usbip-win2: a kernel component that connects first can make an attach fail. The listener does not use SO_REUSEADDR, so a second program cannot share the port; it does not use SO_EXCLUSIVEADDRUSE either, because whether TIME_WAIT connections would then block a restart was not verified.}
Default @code{} disabled @endcode
Example @code{} usb_forwarding_enabled = enabled @endcode

usb_forwarding_port

Description The TCP port of the USB forwarding tunnel. 0 uses the main port + 7. Otherwise the port must be between 1024 and 65535, and must not be one of the ports this host already uses. A value outside that range is ignored with a warning. If the port is busy, USB forwarding stays off.
Default @code{} 0 @endcode
Example @code{} usb_forwarding_port = 48100 @endcode

usb_forwarding_require_stream

Description Only let a client forward a USB device while it has an active stream session.
Default @code{} enabled @endcode
Example @code{} usb_forwarding_require_stream = disabled @endcode

usb_forwarding_control

Description Create a Windows named pipe that lets local management software show and control USB forwarding while Apollo runs. The pipe is named `\\.\pipe\ApolloVibe-usb-control-`, so several Apollo instances on one machine do not collide. There is no network port and no secret: the pipe's access list is the only authentication of the client. Only SYSTEM and BUILTIN\Administrators can open it, remote clients are refused, and a standard user cannot open it. Takes effect after a restart. Windows only. 
        Apollo creates the pipe only when it can make SYSTEM or Administrators its owner. The console Apollo
        normally runs as SYSTEM, so this costs nothing there. An Apollo that runs as a standard user (for
        example a seat's Apollo) does not create the pipe at all: it logs one line and carries on without it.
        Creation also fails closed if the pipe name is already in use, and Apollo checks the owner and the access
        list of every live pipe instance; an instance that does not match is closed and never served. If an
        instance cannot be created, Apollo keeps the one it has and retries with a growing pause. With this
        disabled there is no pipe and no thread.

        @warning{The access list protects the server from the wrong client. It does not protect a client from
        the wrong server: while Apollo is stopped, any local user can create a pipe with this name. Every
        client, whether it runs as SYSTEM or as an administrator, must do all of this before it sends anything:
        (1) pass SECURITY_SQOS_PRESENT and SECURITY_IDENTIFICATION to CreateFile as part of the open (they are
        flags of the open call, not a later step), so the server can never impersonate the client;
        (2) read the pipe's owner with GetSecurityInfo and require S-1-5-18 (SYSTEM) or S-1-5-32-544
        (Administrators); (3) require GetNamedPipeServerProcessId to equal the process id of the Apollo it
        expects. That is the process that owns the listening TCP port of the configured Apollo main port,
        looked up with GetExtendedTcpTable (listener table with owner process ids) again for each connection.
        A process id can be reused after Apollo exits; the window is narrow and the owner check covers it. The
        client must refuse to talk when any check fails. Every read and write must be bounded, with
        FILE_FLAG_OVERLAPPED and a timeout. On ERROR_PIPE_BUSY it should call WaitNamedPipe with a bounded
        timeout, retry a bounded number of times, then fail. A close with no reply means the connection cap
        was reached or Apollo is stopping; treat it as busy, not as an answer. Other administrators and
        SYSTEM-level processes are outside this threat model: an administrator can already stop Apollo and
        take the pipe name, and the owner and process id checks are what separate administrator-level
        processes from ordinary users and from each other.}

        One request per connection. Send one UTF-8 JSON object followed by a newline (at most 4096 bytes
        including the newline) and read one JSON object followed by a newline. A connection that
        sends nothing gets a `timeout` error reply after 5 seconds and is closed after at most 5 more seconds
        (the server waits that long for the client to finish reading). At most 4 connections are served at once;
        the rest are closed without a reply.
        @code{}
        {"v":1,"op":"status"}
        {"v":1,"op":"set_enabled","enabled":true}
        {"v":1,"op":"revoke_client","client_uuid":"<uuid>"}
        {"v":1,"op":"clear_revoke","client_uuid":"<uuid>"}
        @endcode
        Replies are `{"v":1,"ok":true,...}` or `{"v":1,"ok":false,"error":"<code>"}`, with a fixed error code
        that never repeats the request.
        - `status` reports whether USB forwarding is on, whether the tunnel is listening, its port, whether a
          stream is required, the running forwards, each paired client's uuid, name and USB permission, and the
          uuids on the deny list. It never contains the tunnel token, certificates or keys.
        - `set_enabled` starts or stops the tunnel at once, with no restart and no effect on streams. The
          reply says `"persisted":false`: the change lasts only until Apollo restarts, and
          `usb_forwarding_enabled` in the config file decides the next start. Each start uses a new tunnel
          token. A port that `usb_forwarding_port` would not allow is refused (`port_refused`).
        - `revoke_client` adds the client to a deny list and cuts its running forwards. The reply has
          `forwards_cut`, `"denied":true` and `"known"`. Uuids are compared without regard to case. `known` is true
          only when the uuid belongs to a client that is paired right now; an unknown uuid is still denied (denying
          ahead of time is allowed) but the reply says `"known":false`, so a typo is visible. A denied client is refused at the tunnel handshake, at the
          periodic recheck and in the capability reply (reason `forbidden`, no port or token), until Apollo
          restarts or `clear_revoke` removes it. It does not unpair the client and does not change its stored
          permission. The list holds 256 clients. When it is full, entries of clients that are no longer paired are
          dropped first; if it is still full the answer is `deny_list_full` (the forwards are still cut).
        - `clear_revoke` removes a client from the deny list. The reply has `"denied":false` and `"known"`.

        Granting or removing the USB forwarding permission stays in the client page.
    </td>
</tr>
<tr>
    <td>Default</td>
    <td colspan="2">@code{}
        disabled
        @endcode</td>
</tr>
<tr>
    <td>Example</td>
    <td colspan="2">@code{}
        usb_forwarding_control = enabled
        @endcode</td>
</tr>

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.}
Default @code{} 0 @endcode
Example @code{} lan_encryption_mode = 0 @endcode
Choices 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

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.}
Default @code{} 1 @endcode
Example @code{} wan_encryption_mode = 1 @endcode
Choices 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

ping_timeout

Description How long to wait, in milliseconds, for data from Moonlight before shutting down the stream.
Default @code{} 10000 @endcode
Example @code{} ping_timeout = 10000 @endcode

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 @code{} apps.json @endcode
Example @code{} file_apps = apps.json @endcode

credentials_file

Description The file where user credentials for the UI are stored.
Default @code{} sunshine_state.json @endcode
Example @code{} credentials_file = sunshine_state.json @endcode

log_path

Description The path where the Sunshine log is stored.
Default @code{} sunshine.log @endcode
Example @code{} log_path = sunshine.log @endcode

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 @code{} credentials/cakey.pem @endcode
Example @code{} pkey = /dir/pkey.pem @endcode

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 @code{} credentials/cacert.pem @endcode
Example @code{} cert = /dir/cert.pem @endcode

file_state

Description The file where current state of Sunshine is stored.
Default @code{} sunshine_state.json @endcode
Example @code{} file_state = sunshine_state.json @endcode

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 @code{} 20 @endcode
Range 1-255
Example @code{} fec_percentage = 20 @endcode

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 @code{} 28 @endcode
Example @code{} qp = 28 @endcode

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 @code{} 2 @endcode
Example @code{} min_threads = 2 @endcode

limit_framerate

Description Limit the encoded frame rate to the frame rate the client requested when it launched the app. When disabled, the frame rate the client sends when the stream is set up is used instead, which can be higher, for example when a client's warp mode multiplies it. @note{When enabled and a client's warp mode is detected, the bitrate is multiplied by the warp factor.} @note{As reported by the option's text in the web UI, and not verified in the code: the stream may not reach the full frame rate if vsync is enabled, and disabling this option can cause lag on some clients.}
Default @code{} enabled @endcode
Example @code{} limit_framerate = enabled @endcode

envvar_compatibility_mode

Description Change the format of the `SUNSHINE_CLIENT_FPS` environment variable that apps and commands receive, for tools that expect the older format. When disabled, it has three decimal places, for example `59.940`. When enabled, the frame rate is rounded to the nearest whole number. @note{When enabled, the rounded value is currently written with six decimal places, for example `60.000000`. `APOLLO_CLIENT_FPS` is not affected by this option.}
Default @code{} disabled @endcode
Example @code{} envvar_compatibility_mode = enabled @endcode

legacy_ordering

Description Make legacy clients show the app list in the configured order. The app names sent to clients get a hidden prefix of zero-width characters that sorts in that order. Each client can be excluded from this in the web UI, so the per-client setting must also allow it. @warning{Clients or scripts that do not handle UTF-8 correctly may show or process the app names wrongly.} @warning{Do not use this option with exactly one configured app. An exception is thrown while the app list is built, so clients may receive an empty list.}
Default @code{} disabled @endcode
Example @code{} legacy_ordering = enabled @endcode

ignore_encoder_probe_failure

Description When an app is launched while no stream is running, the encoders are probed again. If that probe fails, the launch is refused with status 503. When this option is enabled, a warning is logged and the launch continues. This applies only when a new app is started. Resuming a running app returns 503 on a failed probe regardless of this option. @warning{The stream may then fail if no encoder is actually available.}
Default @code{} disabled @endcode
Example @code{} ignore_encoder_probe_failure = enabled @endcode

input_desktop_wait_timeout

Description How many seconds the capture thread waits for the input desktop to become accessible before it creates the first display. In a session that was just created, Windows shows the logon (Winlogon, secure) desktop first. A normal process is denied access to it (error 5, ACCESS_DENIED), so display capture cannot start until the user desktop appears. This can take about 30 seconds, and much longer while a lock screen or credential prompt is up. Without the wait, the capture fails once and is not retried. The wait ends as soon as the desktop opens, so a normal start is not delayed, and it ends when the session ends. It does not apply to recovery while a stream is running or to the startup encoder probe. If the wait runs out, the log says so and the start continues, which then fails as it did before. A value of 0 turns every wait off, including [input_desktop_wait_request_timeout](#input_desktop_wait_request_timeout). @note{Moonlight gives up on a stream that sends no video for 10 seconds, so a client may disconnect before a long wait ends. Launch requests are covered by the shorter request wait below.} @note{Applies to Windows only.}
Default @code{} 180 @endcode
Example @code{} input_desktop_wait_timeout = 300 @endcode

input_desktop_wait_request_timeout

Description How many seconds a launch or resume request waits for the input desktop to become accessible before the encoder probe. If it is still not accessible, the host answers 503 with a message that asks the client to retry, and the client's retry does the rest of the waiting. Keep this short. The host handles one HTTPS request at a time, so while a request waits, the client's serverinfo polls (5 second timeout in Moonlight) wait too. Launch and resume requests time out after 120 seconds in Moonlight, and Moonlight does not retry them by itself. The value is never larger than [input_desktop_wait_timeout](#input_desktop_wait_timeout). A value of 0 turns the wait off for requests. @note{Applies to Windows only.}
Default @code{} 3 @endcode
Example @code{} input_desktop_wait_request_timeout = 10 @endcode

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.}
Default @code{} 0 @endcode
Example @code{} hevc_mode = 2 @endcode
Choices 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

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.}
Default @code{} 0 @endcode
Example @code{} av1_mode = 2 @endcode
Choices 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

capture

Description Force specific screen capture method.
Default Automatic. Sunshine will use the first capture method available in the order of the table above.
Example @code{} capture = kms @endcode
Choices nvfbc Use NVIDIA Frame Buffer Capture to capture direct to GPU memory. This is usually the fastest method for NVIDIA cards. NvFBC does not have native Wayland support and does not work with XWayland. @note{Applies to Linux only.}
wlr Capture for wlroots based Wayland compositors via wlr-screencopy-unstable-v1. It is possible to capture virtual displays in e.g. Hyprland using this method. @note{Applies to Linux only.}
kms DRM/KMS screen capture from the kernel. This requires that Sunshine has `cap_sys_admin` capability. @note{Applies to Linux only.}
x11 Uses XCB. This is the slowest and most CPU intensive so should be avoided if possible. @note{Applies to Linux only.}
ddx Use DirectX Desktop Duplication API to capture the display. This is well-supported on Windows machines. @note{Applies to Windows only.}
wgc (beta feature) Use Windows.Graphics.Capture to capture the display. @note{Applies to Windows only.} @attention{This capture method is not compatible with the Sunshine service.}

encoder

Description Force a specific encoder.
Default Sunshine will use the first encoder that is available.
Example @code{} encoder = nvenc @endcode
Choices nvenc For NVIDIA graphics cards
quicksync For Intel graphics cards
amdvce For AMD graphics cards
vaapi Use Linux VA-API (AMD, Intel)
software Encoding occurs on the CPU

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](#encoder).}
Default @code{} 1 @endcode
Example @code{} nvenc_preset = 1 @endcode
Choices 1 P1 (fastest)
2 P2
3 P3
4 P4
5 P5
6 P6
7 P7 (slowest)

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](#encoder).}
Default @code{} quarter_res @endcode
Example @code{} nvenc_twopass = quarter_res @endcode
Choices disabled One pass (fastest)
quarter_res Two passes, first pass at quarter resolution (faster)
full_res Two passes, first pass at full resolution (slower)

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](#encoder).} @warning{Enabling this option may reduce performance.}
Default @code{} disabled @endcode
Example @code{} nvenc_spatial_aq = disabled @endcode

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](#encoder).} @warning{Can lead to network packet loss.}
Default @code{} 0 @endcode
Range 0-400
Example @code{} nvenc_vbv_increase = 0 @endcode

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](#encoder).} @note{Applies to Windows only.}
Default @code{} enabled @endcode
Example @code{} nvenc_realtime_hags = enabled @endcode

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](#encoder).} @warning{Disabling this is not recommended since this can lead to significantly increased encoding latency.} @note{Applies to Windows only.}
Default @code{} enabled @endcode
Example @code{} nvenc_latency_over_power = enabled @endcode

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. With this option enabled Sunshine changes global Vulkan/OpenGL present method to "Prefer layered on DXGI Swapchain". This is system-wide setting that is reverted on Sunshine program exit. @note{This option only applies when using NVENC [encoder](#encoder).} @note{Applies to Windows only.}
Default @code{} enabled @endcode
Example @code{} nvenc_opengl_vulkan_on_dxgi = enabled @endcode

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 the NVENC [encoder](#encoder).}
Default @code{} disabled @endcode
Example @code{} nvenc_h264_cavlc = disabled @endcode

nvenc_intra_refresh

Description Intended to enable intra refresh for clients that need it to keep rendering correctly, such as the Xbox client. @attention{This option currently has no effect. It is read from the configuration, but the NVENC encoder does not use it. Intra refresh is turned on only when the client requests it, for HEVC streams on GPUs that support it.}
Default @code{} disabled @endcode
Example @code{} nvenc_intra_refresh = disabled @endcode

Intel QuickSync Encoder

qsv_preset

Description The encoder preset to use. @note{This option only applies when using quicksync [encoder](#encoder).}
Default @code{} medium @endcode
Example @code{} qsv_preset = medium @endcode
Choices 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)

qsv_coder

Description The entropy encoding to use. @note{This option only applies when using H.264 with the quicksync [encoder](#encoder).}
Default @code{} auto @endcode
Example @code{} qsv_coder = auto @endcode
Choices auto let ffmpeg decide
cabac context adaptive binary arithmetic coding - higher quality
cavlc context adaptive variable-length coding - faster decode

qsv_slow_hevc

Description This options enables use of HEVC on older Intel GPUs that only support low power encoding for H.264. @note{This option only applies when using quicksync [encoder](#encoder).} @caution{Streaming performance may be significantly reduced when this option is enabled.}
Default @code{} disabled @endcode
Example @code{} qsv_slow_hevc = disabled @endcode

AMD AMF Encoder

amd_usage

Description The encoder usage profile is used to set the base set of encoding parameters. @note{This option only applies when using amdvce [encoder](#encoder).} @note{The other AMF options that follow will override a subset of the settings applied by your usage profile, but there are hidden parameters set in usage profiles that cannot be overridden elsewhere.}
Default @code{} ultralowlatency @endcode
Example @code{} amd_usage = ultralowlatency @endcode
Choices transcoding transcoding (slowest)
webcam webcam (slow)
lowlatency_high_quality low latency, high quality (fast)
lowlatency low latency (faster)
ultralowlatency ultra low latency (fastest)

amd_rc

Description The encoder rate control. @note{This option only applies when using amdvce [encoder](#encoder).} @warning{The `vbr_latency` option generally works best, but some bitrate overshoots may still occur. Enabling HRD allows all bitrate based rate controls to better constrain peak bitrate, but may result in encoding artifacts depending on your card.}
Default @code{} vbr_latency @endcode
Example @code{} amd_rc = vbr_latency @endcode
Choices cqp constant qp mode
cbr constant bitrate
vbr_latency variable bitrate, latency constrained
vbr_peak variable bitrate, peak constrained

amd_enforce_hrd

Description Enable Hypothetical Reference Decoder (HRD) enforcement to help constrain the target bitrate. @note{This option only applies when using amdvce [encoder](#encoder).} @warning{HRD is known to cause encoding artifacts or negatively affect encoding quality on certain cards.}
Default @code{} disabled @endcode
Example @code{} amd_enforce_hrd = disabled @endcode

amd_quality

Description The quality profile controls the tradeoff between speed and quality of encoding. @note{This option only applies when using amdvce [encoder](#encoder).}
Default @code{} balanced @endcode
Example @code{} amd_quality = balanced @endcode
Choices speed prefer speed
balanced balanced
quality prefer quality

amd_preanalysis

Description Preanalysis can increase encoding quality at the cost of latency. @note{This option only applies when using amdvce [encoder](#encoder).}
Default @code{} disabled @endcode
Example @code{} amd_preanalysis = disabled @endcode

amd_vbaq

Description Variance Based Adaptive Quantization (VBAQ) can increase subjective visual quality by prioritizing allocation of more bits to smooth areas compared to more textured areas. @note{This option only applies when using amdvce [encoder](#encoder).}
Default @code{} enabled @endcode
Example @code{} amd_vbaq = enabled @endcode

amd_coder

Description The entropy encoding to use. @note{This option only applies when using H.264 with the amdvce [encoder](#encoder).}
Default @code{} auto @endcode
Example @code{} amd_coder = auto @endcode
Choices auto let ffmpeg decide
cabac context adaptive binary arithmetic coding - faster decode
cavlc context adaptive variable-length coding - higher quality

VideoToolbox Encoder

vt_coder

Description The entropy encoding to use. @note{This option only applies when using macOS.}
Default @code{} auto @endcode
Example @code{} vt_coder = auto @endcode
Choices auto let ffmpeg decide
cabac context adaptive binary arithmetic coding - faster decode
cavlc context adaptive variable-length coding - higher quality

vt_software

Description Force Video Toolbox to use software encoding. @note{This option only applies when using macOS.}
Default @code{} auto @endcode
Example @code{} vt_software = auto @endcode
Choices auto let ffmpeg decide
disabled disable software encoding
allowed allow software encoding
forced force software encoding

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 @code{} enabled @endcode
Example @code{} vt_realtime = enabled @endcode

VA-API Encoder

vaapi_strict_rc_buffer

Description Enabling this option can avoid dropped frames over the network during scene changes, but video quality may be reduced during motion. @note{This option only applies for H.264 and HEVC when using VA-API [encoder](#encoder) on AMD GPUs.}
Default @code{} disabled @endcode
Example @code{} vaapi_strict_rc_buffer = enabled @endcode

Software Encoder

sw_preset

Description The encoder preset to use. @note{This option only applies when using software [encoder](#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.}
Default @code{} superfast @endcode
Example @code{} sw_preset = superfast @endcode
Choices ultrafast fastest
superfast
veryfast
faster
fast
medium
slow
slower
veryslow slowest

sw_tune

Description The tuning preset to use. @note{This option only applies when using software [encoder](#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. }
Default @code{} zerolatency @endcode
Example @code{} sw_tune = zerolatency @endcode
Choices 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
Previous Next
Legal App Examples
[TOC]