Configuration Reference
Detailed specification of all SolarFlare host settings, Audio FX DSP filters, Opus tuning, and client profiles.
Configuration File Location#
SolarFlare settings live in ~/.config/sunshine/sunshine.conf. You can edit this file directly or configure settings through the Web UI at https://localhost:47990/config.
Fork Host Tunables#
Switch tabs to browse network, scheduling, capture, and access keys. Full fork prose lives in the sections below; inherited upstream keys are summarized in the Developer articles.
Important
Inherited upstream keys are summarized in Building / Porting. Fork keys are fully documented in the sections on this page.
busy_poll_usSO_BUSY_POLL in microseconds on the ENet UDP socket. 0 disables.
busy_poll_us = 50rate_cap_pctPercent of detected link speed used as the send pacer.
rate_cap_pct = 80enet_4mib_bufferGrow ENet UDP send and receive buffers to 4 MiB.
enet_4mib_buffer = truedscp_qosTag streaming UDP with DSCP CS3 for router QoS.
dscp_qos = trueAudio FX Pre-Encoder Processing#
SolarFlare includes a lightweight audio signal processor running between PipeWire capture and Opus encoding:
sf_audio_agcEnable Automatic Gain Control to smooth stream audio loudness levels.
sf_audio_agc_target_dbTarget RMS loudness for automatic gain control.
sf_audio_vadEnable Voice Activity Detection for voice-aware ducking.
sf_audio_duckingDuck game audio volume when voice speech is detected.
sf_audio_ducker_attenuation_dbGame audio attenuation applied when speech is active.
sf_audio_noise_gateApply noise gate to eliminate background microphone hum.
sf_audio_noise_gate_dbThreshold below which audio signal is silenced.
Opus Encoder Tuning#
Fine-tune Opus speech vs music mode, VBR behavior, and forward error correction (FEC):
sf_opus_applicationOpus application tuning mode.
sf_opus_vbrBitrate mode for the audio stream.
sf_opus_complexityEncoder complexity algorithm trade-off (CPU vs compression).
sf_opus_fecIn-band forward error correction to recover lost audio packets.
sf_opus_expected_loss_pctPre-allocate FEC packet redundancy based on expected network loss.
NVENC Tuning Presets#
One-click preset tuning for NVIDIA NVENC encoders without low-level manual flag editing:
nvenc_tuning_presetSingle-knob NVENC profile. 0 enforces zero B-frames and low-delay rate control; 2 enables spatial adaptive quantization.
Webhooks & Client Profiles#
Automate stream lifecycle events and customize bitrates per client device name:
# Webhook notifications on stream start and stop
webhook_url_0 = https://home-assistant.local/api/webhook/solarflare-stream
webhook_secret = super-secret-signing-key
# Per-client profile overrides
client_profile_Phone_max_bitrate = 15000
client_profile_Phone_latency_mode = aggressive
client_profile_LivingRoomTV_max_bitrate = 80000
client_profile_LivingRoomTV_hevc_mode = 2Trust, tokens & webhooks#
trusted_subnet_auto_pairingMaster switch for PIN-less pairing. Clients in trusted_subnets pair without a PIN when enabled. Disabled by default.
trusted_subnet_auto_pairing = falseapi_tokensScoped automation tokens, file-only with no Web UI field. Format name, hash, salt, scopes. Mint via POST /api/tokens; the plaintext is shown once and must be saved to sunshine.conf.
api_tokens = home-assistant hash salt stream:control,logs:getwebhook_secretHMAC-SHA256 secret signing every webhook body as X-Solarflare-Signature: sha256=<hex>. Session history and GET /api/sessions work even with no URLs set.
webhook_secret = super-secret-signing-keyclient_profile_<name>_<field>Per-device overrides keyed by Moonlight client name (uniqueid), file-only. Fields: max_bitrate (kbps ceiling), hevc_mode (0-3), av1_mode (0-3), latency_mode (safe|aggressive). Applied at launch, restored at session end.
client_profile_Phone_max_bitrate = 15000Linux input seat isolation#
New in v1.3.0. input_seat assigns virtual mouse, keyboard, touch, pen, and gamepad devices to a non-default systemd-logind seat (for example seat1). Precedence is input_seat > XDG_SEAT > empty or seat0 (no isolation). The runtime injects a transient udev rule at /run/udev/rules.d/99-solarflare-seat.rules and synthesizes a change uevent per device; a shipped fallback rule can be installed manually where /run/udev is read-only. Same-seat hardening uses exclusive EVIOCGRAB on virtual event nodes. The target seat must exist (loginctl seat-add) with a display or input device attached. Set it in the Web UI Inputs tab (Linux only) or directly in config.
input_seatTarget logind seat for virtual input devices. Empty follows XDG_SEAT; seat0 disables isolation.
input_seat = seat1Headless compositor streaming#
headless_virtual_display is the simple xrandr VIRTUAL1 fallback for monitor-less X11 (independent knob). headless_mode instead routes launches into a private nested compositor. When headless_mode is on, compositor_backend selects labwc, krfb, or gamescope (auto picks krfb-virtualmonitor under KWin, else labwc). Width, height, and refresh of 0 follow the client request.
headless_modeRoute game launches into a private nested compositor instead of hijacking the desktop.
headless_mode = truecompositor_backendHeadless display backend selection.
compositor_backend = labwclinux_use_cage_compositorUse the labwc nested compositor for headless streaming. Requires headless_mode.
linux_use_cage_compositor = trueheadless_widthOverride headless virtual display width. 0 follows the client resolution.
headless_width = 1920headless_heightOverride headless virtual display height. 0 follows the client resolution.
headless_height = 1080headless_refreshOverride headless virtual display refresh rate. 0 follows the client framerate.
headless_refresh = 120Audio DSP full reference#
The seven most-used Audio FX knobs are above. The remaining eleven fine-tune AGC dynamics, VAD sensitivity, and ducker timing:
sf_audio_agc_max_gain_dbMaximum AGC boost applied to quiet audio.
sf_audio_agc_min_gain_dbMaximum AGC cut applied to loud audio.
sf_audio_agc_attack_msGain-up ramp speed once audio drops below target.
sf_audio_agc_hold_msHold time before the gain releases after loud passages.
sf_audio_agc_release_msGain-down ramp speed once audio exceeds target.
sf_audio_vad_threshold_dbSpeech RMS threshold for voice activity detection.
sf_audio_vad_hysteresis_dbAnti-flutter band around the VAD threshold.
sf_audio_vad_min_speech_msSpeech debounce: minimum voiced time before ducking engages.
sf_audio_vad_min_silence_msSilence debounce before ducking releases.
sf_audio_ducker_attack_msDuck-down speed when speech starts.
sf_audio_ducker_release_msDuck recovery speed when speech ends.
sf_opus_bandwidth_extensionAllow super-wideband and fullband Opus above 16 kHz. False restricts to wideband-only.
Inherited upstream option groups#
Every upstream Sunshine key still works. The most-used groups: Video (capture, encoder, adapter_name, output_name, max_bitrate, qp, hevc_mode, av1_mode, sw_preset, sw_tune, plus per-vendor nvenc_*, vaapi_*, qsv_*, amd_*, vt_*, vk_* groups; adaptive bitrate adaptive_bitrate_enabled, adaptive_bitrate_min, adaptive_bitrate_max). Audio (audio_sink, virtual_sink, stream_audio). Network (upnp, address_family, bind_address, port default 47989, external_ip, lan_encryption_mode, wan_encryption_mode, ping_timeout, packetsize, fec_percentage). Input (controller, gamepad, keyboard, mouse, keybindings, DS4/DS5 mapping keys). Security (origin_web_ui_allowed pc|lan|wan, csrf_allowed_origins, pkey, cert). Files and logging (file_apps, file_state, credentials_file, locale, sunshine_name, min_log_level, log_path, global_prep_cmd). The full machine-readable reference is docs/configuration.md in the repo; the Web UI exposes the common subset with inline help.