mirror/Sunshine
1
0
Fork 0
mirror of https://github.com/LizardByte/Sunshine.git synced 2025-04-17 11:43:04 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: drop sphinx and use doxygen exclusively (#2932)
Some checks failed
CI / GitHub Env Debug (push) Has been cancelled
Details
CI / Setup Release (push) Has been cancelled
Details
CI / Setup Flatpak Matrix (push) Has been cancelled
Details
CI Docker / Check Dockerfiles (push) Has been cancelled
Details
CodeQL / Get language matrix (push) Has been cancelled
Details
Build GH-Pages / update_pages (push) Has been cancelled
Details
CI / Linux Flatpak (push) Has been cancelled
Details
CI / Linux ${{ matrix.type }} (--appimage-build, 22.04, AppImage) (push) Has been cancelled
Details
CI / Homebrew (${{ matrix.os_name }}-${{ matrix.os_version }}${{ matrix.release == true && ' (Release)' || '' }}) (macos, 12) (push) Has been cancelled
Details
CI / Homebrew (${{ matrix.os_name }}-${{ matrix.os_version }}${{ matrix.release == true && ' (Release)' || '' }}) (macos, 13) (push) Has been cancelled
Details
CI / Homebrew (${{ matrix.os_name }}-${{ matrix.os_version }}${{ matrix.release == true && ' (Release)' || '' }}) (macos, 14) (push) Has been cancelled
Details
CI / Homebrew (${{ matrix.os_name }}-${{ matrix.os_version }}${{ matrix.release == true && ' (Release)' || '' }}) (ubuntu, latest) (push) Has been cancelled
Details
CI / Homebrew (${{ matrix.os_name }}-${{ matrix.os_version }}${{ matrix.release == true && ' (Release)' || '' }}) (ubuntu, latest, true) (push) Has been cancelled
Details
CI / Macports (macOS-${{ matrix.os_version }}) (12, true) (push) Has been cancelled
Details
CI / Macports (macOS-${{ matrix.os_version }}) (13) (push) Has been cancelled
Details
CI / Macports (macOS-${{ matrix.os_version }}) (14) (push) Has been cancelled
Details
CI / Windows (push) Has been cancelled
Details
CI Docker / Setup Release (push) Has been cancelled
Details
CI Docker / Lint Dockerfile${{ matrix.tag }} (push) Has been cancelled
Details
CI Docker / Docker${{ matrix.tag }} (push) Has been cancelled
Details
CodeQL / Analyze (${{ matrix.name }}) (push) Has been cancelled
Details

Browse Source
This commit is contained in:
ReenigneArcher 2024-08-05 14:44:17 -04:00 committed by GitHub
parent adf068e44e
commit 4bd521bb43
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
67 changed files with 4791 additions and 5307 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
.github/workflows/CI.yml vendored
View File

@ -150,14 +150,14 @@ jobs:
mkdir -p build
mkdir -p artifacts
cd build
cmake -DGITHUB_CLONE_URL=${clone_url} \
-B build \
-S . \
-DBUILD_VERSION=${build_version} \
-DGITHUB_BRANCH=${branch} \
-DGITHUB_COMMIT=${commit} \
-DSUNSHINE_CONFIGURE_FLATPAK_MAN=ON \
-DSUNSHINE_CONFIGURE_ONLY=ON \
..
-DSUNSHINE_CONFIGURE_ONLY=ON
- name: Debug Manifest
working-directory: build
@ -520,9 +520,10 @@ jobs:
echo "Clone URL: ${clone_url}"
echo "Tag: ${tag}"
mkdir build
cd build
mkdir -p build
cmake \
-B build \
-S . \
-DBUILD_VERSION="${build_version}" \
-DFORMULA_VERSION="${version}" \
-DGITHUB_BRANCH="${branch}" \
@ -531,9 +532,7 @@ jobs:
-DGITHUB_DEFAULT_BRANCH="${default_branch}" \
-DGITHUB_TAG="${tag}" \
-DSUNSHINE_CONFIGURE_HOMEBREW=ON \
-DSUNSHINE_CONFIGURE_ONLY=ON \
..
cd ..
-DSUNSHINE_CONFIGURE_ONLY=ON
# copy formula to artifacts
mkdir -p homebrew
@ -654,17 +653,16 @@ jobs:
echo "Commit: ${commit}"
echo "Clone URL: ${clone_url}"
mkdir build
cd build
mkdir -p build
cmake \
-B build \
-S . \
-DBUILD_VERSION=${build_version} \
-DGITHUB_BRANCH=${branch} \
-DGITHUB_COMMIT=${commit} \
-DGITHUB_CLONE_URL=${clone_url} \
-DSUNSHINE_CONFIGURE_PORTFILE=ON \
-DSUNSHINE_CONFIGURE_ONLY=ON \
..
cd ..
-DSUNSHINE_CONFIGURE_ONLY=ON
# copy Portfile to artifacts
mkdir -p artifacts
@ -1024,7 +1022,6 @@ jobs:
Remove-Item -Path doxygen-setup.exe
- name: Setup python
# use this instead of msys2 python due to known issues using wheels, https://www.msys2.org/docs/python/
id: setup-python
uses: actions/setup-python@v5
with:
@ -1048,17 +1045,16 @@ jobs:
BUILD_VERSION: ${{ needs.setup_release.outputs.release_tag }}
COMMIT: ${{ needs.setup_release.outputs.release_commit }}
run: |
mkdir build
cd build
mkdir -p build
cmake \
-B build \
-G Ninja \
-S . \
-DBUILD_WERROR=ON \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DPython_EXECUTABLE='${{ steps.python-path.outputs.python-path }}' \
-DSUNSHINE_ASSETS_DIR=assets \
-DTESTS_SOFTWARE_ENCODER_UNAVAILABLE='skip' \
-G "MinGW Makefiles" \
..
mingw32-make -j$(nproc)
-DTESTS_SOFTWARE_ENCODER_UNAVAILABLE='skip'
ninja -C build
- name: Package Windows
shell: msys2 {0}

1
.gitignore vendored
View File

@ -40,6 +40,7 @@
# build directories
build/
cmake-*/
docs/*-doxyconfig*
# npm
node_modules/

8
.gitmodules vendored
View File

@ -6,10 +6,10 @@
path = third-party/build-deps
url = https://github.com/LizardByte/build-deps.git
branch = dist
[submodule "third-party/doxygen-awesome-css"]
path = third-party/doxygen-awesome-css
url = https://github.com/jothepro/doxygen-awesome-css.git
branch = main
[submodule "third-party/doxyconfig"]
path = third-party/doxyconfig
url = https://github.com/LizardByte/doxyconfig.git
branch = master
[submodule "third-party/googletest"]
path = third-party/googletest
url = https://github.com/google/googletest/

45
.readthedocs.yaml
View File

@ -3,41 +3,38 @@
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python
build:
os: ubuntu-24.04
tools:
python: "miniconda-latest"
apt_packages:
- libboost-locale-dev # required for rstcheck in cpp code block
jobs:
post_build:
- find ./third-party -iname "*.rst" -type f -delete # find and delete rst files in third-party
- rstcheck -r . # lint rst files
# - rstfmt --check --diff -w 120 . # check rst formatting
commands:
# because we are overriding the build commands, we need to setup the environment ourselves
- cat third-party/doxyconfig/environment.yml
- conda env create --quiet --name ${READTHEDOCS_VERSION} --file third-party/doxyconfig/environment.yml
- npm install "@fortawesome/fontawesome-free"
- mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
- mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
- cp node_modules/@fortawesome/fontawesome-free/css/all.min.css ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
- cp node_modules/@fortawesome/fontawesome-free/js/all.min.js ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
- cp -r node_modules/@fortawesome/fontawesome-free/webfonts ${READTHEDOCS_OUTPUT}html/assets/fontawesome/
- |
wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/favicon.ico" \
-O ${READTHEDOCS_OUTPUT}lizardbyte.ico
- |
wget "https://raw.githubusercontent.com/LizardByte/.github/master/branding/logos/logo-128x128.png" \
-O ${READTHEDOCS_OUTPUT}lizardbyte.png
- cp ./third-party/doxyconfig/Doxyfile ./docs/Doxyfile-doxyconfig
- cp ./third-party/doxyconfig/header.html ./docs/header-doxyconfig.html
- cat ./docs/Doxyfile >> ./docs/Doxyfile-doxyconfig
- cd docs && doxygen Doxyfile-doxyconfig
# using conda, we can get newer doxygen and graphviz than ubuntu provide
# https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661
conda:
environment: docs/environment.yml
environment: third-party/doxyconfig/environment.yml
# submodules required for include statements
submodules:
include: all
recursive: true
# Build documentation in the docs/ directory with Sphinx
sphinx:
builder: html
configuration: docs/source/conf.py
fail_on_warning: true
# Using Sphinx, build docs in additional formats
formats: all
python:
install:
- requirements: ./docs/requirements.txt

25
DOCKER_README.md
View File

@ -25,15 +25,15 @@ ENTRYPOINT steam && sunshine
Sunshine images are available with the following tag suffixes, based on their respective base images.
- `archlinux`
- `debian-bullseye`
- `fedora-36`
- `fedora-37`
- `ubuntu-20.04`
- `debian-bookworm`
- `fedora-39`
- `fedora-40`
- `ubuntu-22.04`
- `ubuntu-24.04`
### Tags
You must combine the `SUNSHINE_VERSION` and `SUNSHINE_OS` to determine the tag to pull. The format should be
`<SUNSHINE_VERSION>-<SUNSHINE_OS>`. For example, `latest-ubuntu-22.04`.
`<SUNSHINE_VERSION>-<SUNSHINE_OS>`. For example, `latest-ubuntu-24.04`.
See all our available tags on [docker hub](https://hub.docker.com/r/lizardbyte/sunshine/tags) or
[ghcr](https://github.com/LizardByte/Sunshine/pkgs/container/sunshine/versions) for more info.
@ -152,8 +152,15 @@ The architectures supported by these images are shown in the table below.
|-----------------|--------------|---------------|
| archlinux | ✅ | ❌ |
| debian-bookworm | ✅ | ✅ |
| debian-bullseye | ✅ | ✅ |
| fedora-38 | ✅ | ✅ |
| fedora-39 | ✅ | ✅ |
| ubuntu-20.04 | ✅ | ✅ |
| fedora-39 | ✅ | ❌ |
| fedora-40 | ✅ | ❌ |
| ubuntu-22.04 | ✅ | ✅ |
| ubuntu-24.04 | ✅ | ✅ |
<div class="section_buttons">
| Previous | Next |
|:-------------------------------|-----------------------------------------------------:|
| [Changelog](docs/changelog.md) | [Third-Party Packages](docs/third_party_packages.md) |
</div>

153
README.md Normal file
View File

@ -0,0 +1,153 @@
# Overview
[![GitHub stars](https://img.shields.io/github/stars/lizardbyte/sunshine.svg?logo=github&style=for-the-badge)](https://github.com/LizardByte/Sunshine)
[![GitHub Releases](https://img.shields.io/github/downloads/lizardbyte/sunshine/total.svg?style=for-the-badge&logo=github)](https://github.com/LizardByte/Sunshine/releases/latest)
[![Docker](https://img.shields.io/docker/pulls/lizardbyte/sunshine.svg?style=for-the-badge&logo=docker)](https://hub.docker.com/r/lizardbyte/sunshine)
[![GHCR](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fipitio%2Fbackage%2Fmaster%2Findex%2FLizardByte%2FSunshine%2Fsunshine.json&query=%24.downloads&label=ghcr%20pulls&style=for-the-badge&logo=github)](https://github.com/LizardByte/Sunshine/pkgs/container/sunshine)
[![Winget Version](https://img.shields.io/badge/dynamic/json.svg?color=orange&label=Winget&style=for-the-badge&prefix=v&query=$[-1:].name&url=https%3A%2F%2Fapi.github.com%2Frepos%2Fmicrosoft%2Fwinget-pkgs%2Fcontents%2Fmanifests%2Fl%2FLizardByte%2FSunshine&logo=microsoft)](https://github.com/microsoft/winget-pkgs/tree/master/manifests/l/LizardByte/Sunshine)
[![GitHub Workflow Status (CI)](https://img.shields.io/github/actions/workflow/status/lizardbyte/sunshine/CI.yml.svg?branch=master&label=CI%20build&logo=github&style=for-the-badge)](https://github.com/LizardByte/Sunshine/actions/workflows/CI.yml?query=branch%3Amaster)
[![GitHub Workflow Status (localize)](https://img.shields.io/github/actions/workflow/status/lizardbyte/sunshine/localize.yml.svg?branch=master&label=localize%20build&logo=github&style=for-the-badge)](https://github.com/LizardByte/Sunshine/actions/workflows/localize.yml?query=branch%3Amaster)
[![Read the Docs](https://img.shields.io/readthedocs/sunshinestream.svg?label=Docs&style=for-the-badge&logo=readthedocs)](http://sunshinestream.readthedocs.io)
[![Codecov](https://img.shields.io/codecov/c/gh/LizardByte/Sunshine?token=SMGXQ5NVMJ&style=for-the-badge&logo=codecov&label=codecov)](https://codecov.io/gh/LizardByte/Sunshine)
LizardByte has the full documentation hosted on [Read the Docs](https://sunshinestream.readthedocs.io).
## About
Sunshine is a self-hosted game stream host for Moonlight.
Offering low latency, cloud gaming server capabilities with support for AMD, Intel, and Nvidia GPUs for hardware
encoding. Software encoding is also available. You can connect to Sunshine from any Moonlight client on a variety of
devices. A web UI is provided to allow configuration, and client pairing, from your favorite web browser. Pair from
the local server or any mobile device.
## System Requirements
@warning{These tables are a work in progress. Do not purchase hardware based on this information.}
<table>
<caption id="minimum_requirements">Minimum Requirements</caption>
<tr>
<th>Component</th>
<th>Requirement</th>
</tr>
<tr>
<td rowspan="3">GPU</td>
<td>AMD: VCE 1.0 or higher, see: <a href="https://github.com/obsproject/obs-amd-encoder/wiki/Hardware-Support">obs-amd hardware support</a></td>
</tr>
<tr>
<td>Intel: VAAPI-compatible, see: <a href="https://www.intel.com/content/www/us/en/developer/articles/technical/linuxmedia-vaapi.html">VAAPI hardware support</a></td>
</tr>
<tr>
<td>Nvidia: NVENC enabled cards, see: <a href="https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new">nvenc support matrix</a></td>
</tr>
<tr>
<td rowspan="2">CPU</td>
<td>AMD: Ryzen 3 or higher</td>
</tr>
<tr>
<td>Intel: Core i3 or higher</td>
</tr>
<tr>
<td>RAM</td>
<td>4GB or more</td>
</tr>
<tr>
<td rowspan="5">OS</td>
<td>Windows: 10+ (Windows Server does not support virtual gamepads)</td>
</tr>
<tr>
<td>macOS: 12+</td>
</tr>
<tr>
<td>Linux/Debian: 12+ (bookworm)</td>
</tr>
<tr>
<td>Linux/Fedora: 39+</td>
</tr>
<tr>
<td>Linux/Ubuntu: 22.04+ (jammy)</td>
</tr>
<tr>
<td rowspan="2">Network</td>
<td>Host: 5GHz, 802.11ac</td>
</tr>
<tr>
<td>Client: 5GHz, 802.11ac</td>
</tr>
</table>
<table>
<caption id="4k_suggestions">4k Suggestions</caption>
<tr>
<th>Component</th>
<th>Requirement</th>
</tr>
<tr>
<td rowspan="3">GPU</td>
<td>AMD: Video Coding Engine 3.1 or higher</td>
</tr>
<tr>
<td>Intel: HD Graphics 510 or higher</td>
</tr>
<tr>
<td>Nvidia: GeForce GTX 1080 or higher</td>
</tr>
<tr>
<td rowspan="2">CPU</td>
<td>AMD: Ryzen 5 or higher</td>
</tr>
<tr>
<td>Intel: Core i5 or higher</td>
</tr>
<tr>
<td rowspan="2">Network</td>
<td>Host: CAT5e ethernet or better</td>
</tr>
<tr>
<td>Client: CAT5e ethernet or better</td>
</tr>
</table>
<table>
<caption id="hdr_suggestions">HDR Suggestions</caption>
<tr>
<th>Component</th>
<th>Requirement</th>
</tr>
<tr>
<td rowspan="3">GPU</td>
<td>AMD: Video Coding Engine 3.4 or higher</td>
</tr>
<tr>
<td>Intel: HD Graphics 730 or higher</td>
</tr>
<tr>
<td>Nvidia: Nvidia: Pascal-based GPU (GTX 10-series) or higher</td>
</tr>
<tr>
<td rowspan="2">CPU</td>
<td>AMD: Ryzen 5 or higher</td>
</tr>
<tr>
<td>Intel: Core i5 or higher</td>
</tr>
<tr>
<td rowspan="2">Network</td>
<td>Host: CAT5e ethernet or better</td>
</tr>
<tr>
<td>Client: CAT5e ethernet or better</td>
</tr>
</table>
## Support
Our support methods are listed in our [LizardByte Docs](https://lizardbyte.readthedocs.io/en/latest/about/support.html).
<div class="section_buttons">
| Previous | Next |
|:---------|------------------------------------:|
| | [Overview](docs/getting_started.md) |
</div>

111
README.rst
View File

@ -1,111 +0,0 @@
Overview
========
LizardByte has the full documentation hosted on `Read the Docs <https://sunshinestream.readthedocs.io/>`__.
About
-----
Sunshine is a self-hosted game stream host for Moonlight.
Offering low latency, cloud gaming server capabilities with support for AMD, Intel, and Nvidia GPUs for hardware
encoding. Software encoding is also available. You can connect to Sunshine from any Moonlight client on a variety of
devices. A web UI is provided to allow configuration, and client pairing, from your favorite web browser. Pair from
the local server or any mobile device.
System Requirements
-------------------
.. warning:: This table is a work in progress. Do not purchase hardware based on this.
**Minimum Requirements**
.. csv-table::
:widths: 15, 60
"GPU", "AMD: VCE 1.0 or higher, see: `obs-amd hardware support <https://github.com/obsproject/obs-amd-encoder/wiki/Hardware-Support>`_"
"", "Intel: VAAPI-compatible, see: `VAAPI hardware support <https://www.intel.com/content/www/us/en/developer/articles/technical/linuxmedia-vaapi.html>`_"
"", "Nvidia: NVENC enabled cards, see: `nvenc support matrix <https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new>`_"
"CPU", "AMD: Ryzen 3 or higher"
"", "Intel: Core i3 or higher"
"RAM", "4GB or more"
"OS", "Windows: 10+ (Windows Server does not support virtual gamepads)"
"", "macOS: 12+"
"", "Linux/Debian: 11 (bullseye)"
"", "Linux/Fedora: 39+"
"", "Linux/Ubuntu: 22.04+ (jammy)"
"Network", "Host: 5GHz, 802.11ac"
"", "Client: 5GHz, 802.11ac"
**4k Suggestions**
.. csv-table::
:widths: 15, 60
"GPU", "AMD: Video Coding Engine 3.1 or higher"
"", "Intel: HD Graphics 510 or higher"
"", "Nvidia: GeForce GTX 1080 or higher"
"CPU", "AMD: Ryzen 5 or higher"
"", "Intel: Core i5 or higher"
"Network", "Host: CAT5e ethernet or better"
"", "Client: CAT5e ethernet or better"
**HDR Suggestions**
.. csv-table::
:widths: 15, 60
"GPU", "AMD: Video Coding Engine 3.4 or higher"
"", "Intel: UHD Graphics 730 or higher"
"", "Nvidia: Pascal-based GPU (GTX 10-series) or higher"
"CPU", "AMD: todo"
"", "Intel: todo"
"Network", "Host: CAT5e ethernet or better"
"", "Client: CAT5e ethernet or better"
Integrations
------------
.. image:: https://img.shields.io/github/actions/workflow/status/lizardbyte/sunshine/CI.yml.svg?branch=master&label=CI%20build&logo=github&style=for-the-badge
:alt: GitHub Workflow Status (CI)
:target: https://github.com/LizardByte/Sunshine/actions/workflows/CI.yml?query=branch%3Amaster
.. image:: https://img.shields.io/github/actions/workflow/status/lizardbyte/sunshine/localize.yml.svg?branch=master&label=localize%20build&logo=github&style=for-the-badge
:alt: GitHub Workflow Status (localize)
:target: https://github.com/LizardByte/Sunshine/actions/workflows/localize.yml?query=branch%3Amaster
.. image:: https://img.shields.io/readthedocs/sunshinestream.svg?label=Docs&style=for-the-badge&logo=readthedocs
:alt: Read the Docs
:target: http://sunshinestream.readthedocs.io/
.. image:: https://img.shields.io/codecov/c/gh/LizardByte/Sunshine?token=SMGXQ5NVMJ&style=for-the-badge&logo=codecov&label=codecov
:alt: Codecov
:target: https://codecov.io/gh/LizardByte/Sunshine
Support
-------
Our support methods are listed in our
`LizardByte Docs <https://lizardbyte.readthedocs.io/en/latest/about/support.html>`__.
Downloads
---------
.. image:: https://img.shields.io/github/downloads/lizardbyte/sunshine/total.svg?style=for-the-badge&logo=github
:alt: GitHub Releases
:target: https://github.com/LizardByte/Sunshine/releases/latest
.. image:: https://img.shields.io/docker/pulls/lizardbyte/sunshine.svg?style=for-the-badge&logo=docker
:alt: Docker
:target: https://hub.docker.com/r/lizardbyte/sunshine
.. image:: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fipitio%2Fghcr-pulls%2Fmaster%2Findex.json&query=%24%5B%3F(%40.owner%3D%3D%22LizardByte%22%20%26%26%20%40.repo%3D%3D%22Sunshine%22%20%26%26%20%40.image%3D%3D%22sunshine%22)%5D.pulls&label=ghcr%20pulls&style=for-the-badge&logo=github
:alt: GHCR
:target: https://github.com/LizardByte/Sunshine/pkgs/container/sunshine
.. image:: https://img.shields.io/badge/dynamic/json.svg?color=orange&label=Winget&style=for-the-badge&prefix=v&query=$[-1:].name&url=https%3A%2F%2Fapi.github.com%2Frepos%2Fmicrosoft%2Fwinget-pkgs%2Fcontents%2Fmanifests%2Fl%2FLizardByte%2FSunshine&logo=microsoft
:alt: Winget Version
:target: https://github.com/microsoft/winget-pkgs/tree/master/manifests/l/LizardByte/Sunshine
Stats
------
.. image:: https://img.shields.io/github/stars/lizardbyte/sunshine.svg?logo=github&style=for-the-badge
:alt: GitHub stars
:target: https://github.com/LizardByte/Sunshine

2
cmake/targets/common.cmake
View File

@ -63,7 +63,7 @@ add_custom_target(web-ui ALL
# docs
if(BUILD_DOCS)
add_subdirectory(docs)
add_subdirectory(third-party/doxyconfig docs)
endif()
# tests

2
docker/clion-toolchain.dockerfile
View File

@ -53,8 +53,6 @@ apt-get install -y --no-install-recommends \
libxfixes-dev \
libxrandr-dev \
libxtst-dev \
python3.10 \
python3.10-venv \
udev \
wget \
x11-xserver-utils \

126
docs/CMakeLists.txt
View File

@ -1,126 +0,0 @@
cmake_minimum_required(VERSION 3.19)
# find doxygen and graphviz
find_package(Doxygen
REQUIRED dot)
if(POLICY CMP0094) # https://cmake.org/cmake/help/latest/policy/CMP0094.html
cmake_policy(SET CMP0094 NEW) # FindPython should return the first matching Python
endif()
# needed on GitHub Actions CI: actions/setup-python does not touch registry/frameworks on Windows/macOS
# this mirrors PythonInterp behavior which did not consult registry/frameworks first
if(NOT DEFINED Python_FIND_REGISTRY)
set(Python_FIND_REGISTRY "LAST") # cmake-lint: disable=C0103
endif()
if(NOT DEFINED Python_FIND_FRAMEWORK)
set(Python_FIND_FRAMEWORK "LAST") # cmake-lint: disable=C0103
endif()
# find python
if(NOT DEFINED Python_EXECUTABLE)
find_package(Python3 3.9 REQUIRED COMPONENTS Interpreter)
else()
set(Python3_EXECUTABLE "${Python_EXECUTABLE}") # cmake-lint: disable=C0103
message(STATUS "Using Python3_EXECUTABLE: ${Python3_EXECUTABLE}")
endif()
# create venv in build dir
set(VENV_DIR "${CMAKE_BINARY_DIR}/venv")
# create venv
execute_process(
COMMAND ${Python3_EXECUTABLE} -m venv ${VENV_DIR}
COMMAND_ERROR_IS_FATAL LAST
RESULT_VARIABLE VENV_RESULT
)
unset(Python3_EXECUTABLE)
set(VENV_PATTERNS
${VENV_DIR}/bin/python
${VENV_DIR}/bin/python.exe
${VENV_DIR}/Scripts/python.exe
)
# set Python3_EXECUTABLE to the python interpreter in the venv
foreach(pattern ${VENV_PATTERNS})
if(EXISTS ${pattern})
set(Python3_EXECUTABLE "${pattern}") # cmake-lint: disable=C0103
get_filename_component(Python3_ROOT_DIR ${pattern} DIRECTORY)
message(STATUS "Using Python3_EXECUTABLE (venv): ${Python3_EXECUTABLE}")
message(STATUS "Using Python3_ROOT_DIR (venv): ${Python3_ROOT_DIR}")
break()
endif()
endforeach()
# fail if Python3_ROOT_DIR is not set
if(NOT DEFINED Python3_EXECUTABLE)
message(FATAL_ERROR "Unable to setup python venv")
endif()
# call a simple python command
execute_process(
COMMAND ${Python3_EXECUTABLE} -c "print(' Testing Python3_EXECUTABLE')"
COMMAND_ERROR_IS_FATAL ANY
RESULT_VARIABLE PYTHON_RESULT
)
# fail if the python command failed
if(NOT PYTHON_RESULT EQUAL 0)
message(FATAL_ERROR "Python3_EXECUTABLE failed")
endif()
# install doc requirements
execute_process(
COMMAND ${Python3_EXECUTABLE} -m pip install -r ${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt
COMMAND_ERROR_IS_FATAL ANY
RESULT_VARIABLE PIP_RESULT
)
# rst check
set(RST_PATTERNS
${CMAKE_CURRENT_SOURCE_DIR}
${CMAKE_SOURCE_DIR}/README.rst
)
# check rst files
foreach(pattern ${RST_PATTERNS})
message(STATUS "Checking RST files: ${pattern}")
execute_process(
COMMAND "${Python3_ROOT_DIR}/rstcheck" -r "${pattern}"
COMMAND_ERROR_IS_FATAL ANY
RESULT_VARIABLE RST_RESULT
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
)
endforeach()
# commands
list(APPEND SPHINX_BUILD_HTML_COMMAND
"${Python3_ROOT_DIR}/sphinx-build"
"-M"
"html"
"${CMAKE_CURRENT_SOURCE_DIR}/source"
"${CMAKE_CURRENT_BINARY_DIR}/build/html"
"-W"
"--keep-going"
)
list(APPEND SPHINX_BUILD_EPUB_COMMAND
"${Python3_ROOT_DIR}/sphinx-build"
"-M"
"epub"
"${CMAKE_CURRENT_SOURCE_DIR}/source"
"${CMAKE_CURRENT_BINARY_DIR}/build/epub"
"-W"
"--keep-going"
)
# build docs
add_custom_target(docs ALL
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
COMMENT "Building documentation"
COMMAND ${CMAKE_COMMAND} -E env DOXY_PATH=$<TARGET_FILE:Doxygen::doxygen> ${SPHINX_BUILD_HTML_COMMAND}
COMMAND ${CMAKE_COMMAND} -E env DOXY_PATH=$<TARGET_FILE:Doxygen::doxygen> ${SPHINX_BUILD_EPUB_COMMAND}
VERBATIM
)

95
docs/Doxyfile
View File

@ -21,82 +21,39 @@
# replacement variables:
# doxygen -x_noenv [configFile]
# must be first
DOXYFILE_ENCODING = UTF-8
ALIASES = ""
ALIASES += "examples=^^**Examples**^^@code{.cpp}"
ALIASES += "examples_end=@endcode^^"
ALIASES += "rst=^^\verbatim embed:rst:leading-asterisk^^"
ALIASES += "rst_end=\endverbatim"
CASE_SENSE_NAMES = YES
DISABLE_INDEX = NO
DOCBOOK_OUTPUT = doxydocbook
# project metadata
DOCSET_BUNDLE_ID = dev.lizardbyte.Sunshine
DOCSET_PUBLISHER_ID = dev.lizardbyte.Sunshine.documentation
DOCSET_PUBLISHER_NAME = LizardByte
DOT_GRAPH_MAX_NODES = 60
DOT_IMAGE_FORMAT = svg
# TODO: On Windows, Doxygen hangs when creating dot graphs if this is set to 0
DOT_NUM_THREADS = 1
EXTRACT_ALL = NO
FULL_SIDEBAR = NO
GENERATE_HTML = YES
GENERATE_LATEX = NO
GENERATE_TREEVIEW = YES
# TODO: Sphinx/Breathe does not support Objective-C right now, so disable XML
# https://github.com/breathe-doc/breathe/issues/129
GENERATE_XML = NO
HAVE_DOT = YES
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
HTML_COPY_CLIPBOARD = NO # required for Doxygen >= 1.10.0
HTML_EXTRA_FILES = ../third-party/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
HTML_EXTRA_FILES += ../third-party/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
HTML_EXTRA_STYLESHEET = ../third-party/doxygen-awesome-css/doxygen-awesome.css
HTML_HEADER = doxygen/header.html
HTML_OUTPUT = doxyhtml
INCLUDE_PATH = ../third-party/build-deps/ffmpeg/Linux-x86_64/include/
INPUT = ../src
INTERACTIVE_SVG = YES
LATEX_OUTPUT = doxylatex
MACRO_EXPANSION = YES
MAN_OUTPUT = doxyman
NUM_PROC_THREADS = 1
PREDEFINED = DOXYGEN
PREDEFINED += __APPLE__
PREDEFINED += linux
PREDEFINED += __linux
PREDEFINED += __linux__
PREDEFINED += __MACH__
PREDEFINED += _WIN32
PREDEFINED += SUNSHINE_BUILD_WAYLAND
PREDEFINED += SUNSHINE_TRAY=1
PROJECT_BRIEF = "Self-hosted game stream host for Moonlight."
PROJECT_ICON = ../sunshine.ico
PROJECT_LOGO = ../sunshine.png
PROJECT_NAME = Sunshine
OUTPUT_DIRECTORY = build/doxygen
RECURSIVE = YES
RTF_OUTPUT = doxyrtf
SORT_BRIEF_DOCS = YES
STRIP_FROM_INC_PATH = ../
STRIP_FROM_PATH = ../
WARN_AS_ERROR = FAIL_ON_WARNINGS
# project specific settings
DOT_GRAPH_MAX_NODES = 60
IMAGE_PATH = ../docs/images
INCLUDE_PATH = ../third-party/build-deps/ffmpeg/Linux-x86_64/include/
PREDEFINED += SUNSHINE_BUILD_WAYLAND
PREDEFINED += SUNSHINE_TRAY=1
# TODO: Enable this when we have complete documentation
WARN_IF_UNDOCUMENTED = NO
WARN_IF_DOC_ERROR = YES
WARN_IF_INCOMPLETE_DOC = YES
WARN_IF_UNDOC_ENUM_VAL = YES
WARN_NO_PARAMDOC = YES
WARNINGS = YES
XML_OUTPUT = doxyxml
# files and directories to process
USE_MDFILE_AS_MAINPAGE = ../README.md
INPUT = ../README.md \
getting_started.md \
changelog.md \
../DOCKER_README.md \
third_party_packages.md \
gamestream_migration.md \
legal.md \
configuration.md \
app_examples.md \
guides.md \
performance_tuning.md \
troubleshooting.md \
building.md \
contributing.md \
../third-party/doxyconfig/docs/source_code.md \
../src

20
docs/Makefile
View File

@ -1,20 +0,0 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?= -W --keep-going
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

325
docs/app_examples.md Normal file
View File

@ -0,0 +1,325 @@
# App Examples
Since not all applications behave the same, we decided to create some examples to help you get started adding games
and applications to Sunshine.
@attention{Throughout these examples, any fields not shown are left blank. You can enhance your experience by
adding an image or a log file (via the `Output` field).}
@note{When a working directory is not specified, it defaults to the folder where the target application resides.}
## Common Examples
### Desktop
| Field | Value |
|------------------|----------------------------|
| Application Name | @code{}Desktop@endcode |
| Image | @code{}desktop.png@endcode |
### Steam Big Picture
@note{Steam is launched as a detached command because Steam starts with a process that self updates itself and the original
process is killed.}
@tabs{
@tab{Linux | <!-- -->
\| Field \| Value \|
\|-------------------\|-----------------------------------------------------\|
\| Application Name \| @code{}Steam Big Picture@endcode \|
\| Detached Commands \| @code{}setsid steam steam://open/bigpicture@endcode \|
\| Image \| @code{}steam.png@endcode \|
}
@tab{macOS | <!-- -->
\| Field \| Value \|
\|-------------------\|---------------------------------------------------\|
\| Application Name \| @code{}Steam Big Picture@endcode \|
\| Detached Commands \| @code{}open steam steam://open/bigpicture@endcode \|
\| Image \| @code{}steam.png@endcode \|
}
@tab{Windows | <!-- -->
\| Field \| Value \|
\|-------------------\|----------------------------------------\|
\| Application Name \| @code{}Steam Big Picture@endcode \|
\| Detached Commands \| @code{}steam://open/bigpicture@endcode \|
\| Image \| @code{}steam.png@endcode \|
}
}
### Epic Game Store game
@note{Using URI method will be the most consistent between various games.}
#### URI
@tabs{
@tab{Windows | <!-- -->
\| Field \| Value \|
\|------------------\|-------------------------------------------------------------------------------------------------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Commands \| @code{}com.epicgames.launcher://apps/d759128018124dcabb1fbee9bb28e178%3A20729b9176c241f0b617c5723e70ec2d%3AOvenbird?action=launch&silent=true@endcode \|
}
}
#### Binary (w/ working directory
@tabs{
@tab{Windows | <!-- -->
\| Field \| Value \|
\|-------------------\|------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Command \| @code{}MarsEpic.exe@endcode \|
\| Working Directory \| @code{}"C:\Program Files\Epic Games\SurvivingMars"@endcode \|
}
}
#### Binary (w/o working directory)
@tabs{
@tab{Windows | <!-- -->
\| Field \| Value \|
\|-------------------\|-------------------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Command \| @code{}"C:\Program Files\Epic Games\SurvivingMars\MarsEpic.exe"@endcode \|
}
}
### Steam game
@note{Using URI method will be the most consistent between various games.}
#### URI
@tabs{
@tab{Linux | <!-- -->
\| Field \| Value \|
\|-------------------\|------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Detached Commands \| @code{}setsid steam steam://rungameid/464920@endcode \|
}
@tab{macOS | <!-- -->
\| Field \| Value \|
\|-------------------\|----------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Detached Commands \| @code{}open steam://rungameid/464920@endcode \|
}
@tab{Windows | <!-- -->
\| Field \| Value \|
\|-------------------\|-----------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Detached Commands \| @code{}steam://rungameid/464920@endcode \|
}
}
#### Binary (w/ working directory
@tabs{
@tab{Linux | <!-- -->
\| Field \| Value \|
\|-------------------\|--------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Command \| @code{}MarsSteam@endcode \|
\| Working Directory \| @code{}~/.steam/steam/SteamApps/common/Survivng Mars@endcode \|
}
@tab{macOS | <!-- -->
\| Field \| Value \|
\|-------------------\|--------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Command \| @code{}MarsSteam@endcode \|
\| Working Directory \| @code{}~/.steam/steam/SteamApps/common/Survivng Mars@endcode \|
}
@tab{Windows | <!-- -->
\| Field \| Value \|
\|-------------------\|-------------------------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Command \| @code{}MarsSteam.exe@endcode \|
\| Working Directory \| @code{}"C:\Program Files (x86)\Steam\steamapps\common\Surviving Mars"@endcode \|
}
}
#### Binary (w/o working directory)
@tabs{
@tab{Linux | <!-- -->
\| Field \| Value \|
\|-------------------\|------------------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Command \| @code{}~/.steam/steam/SteamApps/common/Survivng Mars/MarsSteam@endcode \|
}
@tab{macOS | <!-- -->
\| Field \| Value \|
\|-------------------\|------------------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Command \| @code{}~/.steam/steam/SteamApps/common/Survivng Mars/MarsSteam@endcode \|
}
@tab{Windows | <!-- -->
\| Field \| Value \|
\|-------------------\|---------------------------------------------------------------------------------------------\|
\| Application Name \| @code{}Surviving Mars@endcode \|
\| Command \| @code{}"C:\Program Files (x86)\Steam\steamapps\common\Surviving Mars\MarsSteam.exe"@endcode \|
}
}
### Prep Commands
#### Changing Resolution and Refresh Rate
##### Linux
###### X11
| Prep Step | Command |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------|
| Do | @code{}sh -c "xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}"@endcode |
| Undo | @code{}xrandr --output HDMI-1 --mode 3840x2160 --rate 120@endcode |
@hint{The above only works if the xrandr mode already exists. You will need to create new modes to stream to macOS
and iOS devices, since they use non standard resolutions.
You can update the ``Do`` command to this:
```bash
bash -c "${HOME}/scripts/set-custom-res.sh \"${SUNSHINE_CLIENT_WIDTH}\" \"${SUNSHINE_CLIENT_HEIGHT}\" \"${SUNSHINE_CLIENT_FPS}\""
```
The `set-custom-res.sh` will have this content:
```bash
#!/bin/bash
set -e
# Get params and set any defaults
width=${1:-1920}
height=${2:-1080}
refresh_rate=${3:-60}
# You may need to adjust the scaling differently so the UI/text isn't too small / big
scale=${4:-0.55}
# Get the name of the active display
display_output=$(xrandr | grep " connected" | awk '{ print $1 }')
# Get the modeline info from the 2nd row in the cvt output
modeline=$(cvt ${width} ${height} ${refresh_rate} | awk 'FNR == 2')
xrandr_mode_str=${modeline//Modeline \"*\" /}
mode_alias="${width}x${height}"
echo "xrandr setting new mode ${mode_alias} ${xrandr_mode_str}"
xrandr --newmode ${mode_alias} ${xrandr_mode_str}
xrandr --addmode ${display_output} ${mode_alias}
# Reset scaling
xrandr --output ${display_output} --scale 1
# Apply new xrandr mode
xrandr --output ${display_output} --primary --mode ${mode_alias} --pos 0x0 --rotate normal --scale ${scale}
# Optional reset your wallpaper to fit to new resolution
# xwallpaper --zoom /path/to/wallpaper.png
```
}
###### Wayland
| Prep Step | Command |
|-----------|------------------------------------------------------------------------------------------------------------------------------------------|
| Do | @code{}sh -c "wlr-xrandr --output HDMI-1 --mode \"${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}Hz\""@endcode |
| Undo | @code{}wlr-xrandr --output HDMI-1 --mode 3840x2160@120Hz@endcode |
@hint{`wlr-xrandr` only works with wlroots-based compositors.}
###### Gnome (Wayland, X11)
| Prep Step | Command |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------|
| Do | @code{}sh -c "xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}"@endcode |
| Undo | @code{}xrandr --output HDMI-1 --mode 3840x2160 --rate 120@endcode |
The commands above are valid for an X11 session but won't work for
Wayland. In that case `xrandr` must be replaced by [gnome-randr.py](https://gitlab.com/Oschowa/gnome-randr).
This script is intended as a drop-in replacement with the same syntax. (It can be saved in
`/usr/local/bin` and needs to be made executable.)
###### KDE Plasma (Wayland, X11)
| Prep Step | Command |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------|
| Do | @code{}sh -c "kscreen-doctor output.HDMI-A-1.mode.${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}"@endcode |
| Undo | @code{}kscreen-doctor output.HDMI-A-1.mode.3840x2160@120@endcode |
###### NVIDIA
| Prep Step | Command |
|-----------|-------------------------------------------------------------------------------------------------------------|
| Do | @code{}sh -c "${HOME}/scripts/set-custom-res.sh ${SUNSHINE_CLIENT_WIDTH} ${SUNSHINE_CLIENT_HEIGHT}"@endcode |
| Undo | @code{}sh -c "${HOME}/scripts/set-custom-res.sh 3840 2160"@endcode |
The ``set-custom-res.sh`` will have this content:
```bash
#!/bin/bash
set -e
# Get params and set any defaults
width=${1:-1920}
height=${2:-1080}
output=${3:-HDMI-1}
nvidia-settings -a CurrentMetaMode="${output}: nvidia-auto-select { ViewPortIn=${width}x${height}, ViewPortOut=${width}x${height}+0+0 }"
```
##### macOS
###### displayplacer
@note{This example uses the `displayplacer` tool to change the resolution.
This tool can be installed following instructions in their
[GitHub repository](https://github.com/jakehilborn/displayplacer)}.
| Prep Step | Command |
|-----------|----------------------------------------------------------------------------------------------------|
| Do | @code{}displayplacer "id:<screenId> res:1920x1080 hz:60 scaling:on origin:(0,0) degree:0"@endcode |
| Undo | @code{}displayplacer "id:<screenId> res:3840x2160 hz:120 scaling:on origin:(0,0) degree:0"@endcode |
##### Windows
###### QRes
@note{This example uses the *QRes* tool to change the resolution and refresh rate.
This tool can be downloaded from their [SourceForge repository](https://sourceforge.net/projects/qres).}.
| Prep Step | Command |
|-----------|-------------------------------------------------------------------------------------------------------------------------|
| Do | @code{}cmd /C FullPath\qres.exe /x:%SUNSHINE_CLIENT_WIDTH% /y:%SUNSHINE_CLIENT_HEIGHT% /r:%SUNSHINE_CLIENT_FPS%@endcode |
| Undo | @code{}cmd /C FullPath\qres.exe /x:3840 /y:2160 /r:120@endcode |
### Additional Considerations
#### Linux (Flatpak)
@attention{Because Flatpak packages run in a sandboxed environment and do not normally have access to the
host, the Flatpak of Sunshine requires commands to be prefixed with `flatpak-spawn --host`.}
#### Windows
**Elevating Commands (Windows)**
If you've installed Sunshine as a service (default), you can specify if a command should be elevated with
administrative privileges. Simply enable the elevated option in the WEB UI, or add it to the JSON configuration.
This is an option for both prep-cmd and regular commands and will launch the process with the current user without a
UAC prompt.
@note{It is important to write the values "true" and "false" as string values, not as the typical true/false
values in most JSON.}
**Example**
```json
{
"name": "Game With AntiCheat that Requires Admin",
"output": "",
"cmd": "ping 127.0.0.1",
"exclude-global-prep-cmd": "false",
"elevated": "true",
"prep-cmd": [
{
"do": "powershell.exe -command \"Start-Streaming\"",
"undo": "powershell.exe -command \"Stop-Streaming\"",
"elevated": "false"
}
],
"image-path": ""
}
```
<div class="section_buttons">
| Previous | Next |
|:----------------------------------|--------------------:|
| [Configuration](configuration.md) | [Guides](guides.md) |
</div>

162
docs/building.md Normal file
View File

@ -0,0 +1,162 @@
# Building
Sunshine binaries are built using [CMake](https://cmake.org) and requires `cmake` > 3.25.
## Building Locally
### Dependencies
#### Linux
Dependencies vary depending on the distribution. You can reference our
[linux_build.sh](https://github.com/LizardByte/Sunshine/blob/master/scripts/linux_build.sh) script for a list of
dependencies we use in Debian-based and Fedora-based distributions. Please submit a PR if you would like to extend the
script to support other distributions.
##### CUDA Toolkit
Sunshine requires CUDA Toolkit for NVFBC capture. There are two caveats to CUDA:
1. The version installed depends on the version of GCC.
2. The version of CUDA you use will determine compatibility with various GPU generations.
At the time of writing, the recommended version to use is CUDA ~11.8.
See [CUDA compatibility](https://docs.nvidia.com/deploy/cuda-compatibility/index.html) for more info.
@tip{To install older versions, select the appropriate run file based on your desired CUDA version and architecture
according to [CUDA Toolkit Archive](https://developer.nvidia.com/cuda-toolkit-archive)}
#### macOS
You can either use [Homebrew](https://brew.sh) or [MacPorts](https://www.macports.org) to install dependencies.
##### Homebrew
```bash
dependencies=(
"boost" # Optional
"cmake"
"doxygen" # Optional, for docs
"graphviz" # Optional, for docs
"icu4c" # Optional, if boost is not installed
"miniupnpc"
"node"
"openssl@3"
"opus"
"pkg-config"
)
brew install ${dependencies[@]}
```
If there are issues with an SSL header that is not found:
@tabs{
@tab{ Intel | ```bash
ln -s /usr/local/opt/openssl/include/openssl /usr/local/include/openssl
```}
@tab{ Apple Silicon | ```bash
ln -s /opt/homebrew/opt/openssl/include/openssl /opt/homebrew/include/openssl
```
}
}
##### MacPorts
```bash
dependencies=(
"cmake"
"curl"
"doxygen" # Optional, for docs
"graphviz" # Optional, for docs
"libopus"
"miniupnpc"
"npm9"
"pkgconfig"
)
sudo port install ${dependencies[@]}
```
#### Windows
First you need to install [MSYS2](https://www.msys2.org), then startup "MSYS2 UCRT64" and execute the following
commands.
##### Update all packages
```bash
pacman -Syu
```
##### Install dependencies
```bash
dependencies=(
"doxygen" # Optional, for docs
"git"
"mingw-w64-ucrt-x86_64-boost" # Optional
"mingw-w64-ucrt-x86_64-cmake"
"mingw-w64-ucrt-x86_64-cppwinrt"
"mingw-w64-ucrt-x86_64-curl"
"mingw-w64-ucrt-x86_64-graphviz" # Optional, for docs
"mingw-w64-ucrt-x86_64-miniupnpc"
"mingw-w64-ucrt-x86_64-nlohmann-json"
"mingw-w64-ucrt-x86_64-nodejs"
"mingw-w64-ucrt-x86_64-nsis"
"mingw-w64-ucrt-x86_64-onevpl"
"mingw-w64-ucrt-x86_64-openssl"
"mingw-w64-ucrt-x86_64-opus"
"mingw-w64-ucrt-x86_64-toolchain"
)
pacman -S ${dependencies[@]}
```
### Clone
Ensure [git](https://git-scm.com) is installed on your system, then clone the repository using the following command:
```bash
git clone https://github.com/lizardbyte/sunshine.git --recurse-submodules
cd sunshine
mkdir build
```
### Build
```bash
cmake -B build -G Ninja -S .
ninja -C build
```
@tip{Available build options can be found in
[options.cmake](https://github.com/LizardByte/Sunshine/blob/master/cmake/prep/options.cmake).}
### Package
@tabs{
@tab{Linux | @tabs{
@tab{deb | ```bash
cpack -G DEB --config ./build/CPackConfig.cmake
```}
@tab{rpm | ```bash
cpack -G RPM --config ./build/CPackConfig.cmake
```}
}}
@tab{macOS | @tabs{
@tab{DragNDrop | ```bash
cpack -G DragNDrop --config ./build/CPackConfig.cmake
```}
}}
@tab{Windows | @tabs{
@tab{Installer | ```bash
cpack -G NSIS --config ./build/CPackConfig.cmake
```}
@tab{Portable | ```bash
cpack -G ZIP --config ./build/CPackConfig.cmake
```}
}}
}
### Remote Build
It may be beneficial to build remotely in some cases. This will enable easier building on different operating systems.
1. Fork the project
2. Activate workflows
3. Trigger the *CI* workflow manually
4. Download the artifacts/binaries from the workflow run summary
<div class="section_buttons">
| Previous | Next |
|:--------------------------------------|--------------------------------:|
| [Troubleshooting](troubleshooting.md) | [Contributing](contributing.md) |
</div>

17
docs/changelog.md Normal file
View File

@ -0,0 +1,17 @@
# Changelog
@htmlonly
<script type="module" src="https://md-block.verou.me/md-block.js"></script>
<md-block
hmin="2"
src="https://raw.githubusercontent.com/LizardByte/Sunshine/changelog/CHANGELOG.md">
</md-block>
@endhtmlonly
<div class="section_buttons">
| Previous | Next |
|:--------------------------------------|------------------------------:|
| [Getting Started](getting_started.md) | [Docker](../DOCKER_README.md) |
</div>

2456
docs/configuration.md Normal file
View File

File diff suppressed because it is too large Load Diff

195
docs/contributing.md Normal file
View File

@ -0,0 +1,195 @@
# Contributing
Read our contribution guide in our organization level
[docs](https://lizardbyte.readthedocs.io/en/latest/developers/contributing.html).
## Project Patterns
### Web UI
* The Web UI uses [Vite](https://vitejs.dev) as its build system.
* The HTML pages used by the Web UI are found in `./src_assets/common/assets/web`.
* [EJS](https://www.npmjs.com/package/vite-plugin-ejs) is used as a templating system for the pages
(check `template_header.html` and `template_header_main.html`).
* The Style System is provided by [Bootstrap](https://getbootstrap.com).
* The JS framework used by the more interactive pages is [Vus.js](https://vuejs.org).
#### Building
@tabs{
@tab{CMake | ```bash
cmake -B build -G Ninja -S . --target web-ui
ninja -C build web-ui
```}
@tab{Manual | ```bash
npm run dev
```}
}
### Localization
Sunshine and related LizardByte projects are being localized into various languages.
The default language is `en` (English).
![](https://app.lizardbyte.dev/uno/crowdin/LizardByte_graph.svg)
@admonition{Community | We are looking for language coordinators to help approve translations.
The goal is to have the bars above filled with green!
If you are interesting, please reach out to us on our Discord server.}
#### CrowdIn
The translations occur on [CrowdIn][crowdin-url].
Anyone is free to contribute to the localization there.
##### Translation Basics
* The brand names *LizardByte* and *Sunshine* should never be translated.
* Other brand names should never be translated. Examples include *AMD*, *Intel*, and *NVIDIA*.
##### CrowdIn Integration
How does it work?
When a change is made to Sunshine source code, a workflow generates new translation templates
that get pushed to CrowdIn automatically.
When translations are updated on CrowdIn, a push gets made to the *l10n_master* branch and a PR is made against the
*master* branch. Once the PR is merged, all updated translations are part of the project and will be included in the
next release.
#### Extraction
##### Web UI
Sunshine uses [Vue I18n](https://vue-i18n.intlify.dev) for localizing the UI.
The following is a simple example of how to use it.
* Add the string to the `./src_assets/common/assets/web/public/assets/locale/en.json` file, in English.
```json
{
"index": {
"welcome": "Hello, Sunshine!"
}
}
```
@note{The json keys should be sorted alphabetically. You can use [jsonabc](https://novicelab.org/jsonabc)
to sort the keys.}
@attention{Due to the integration with Crowdin, it is important to only add strings to the *en.json* file,
and to not modify any other language files. After the PR is merged, the translations can take place
on [CrowdIn][crowdin-url]. Once the translations are complete, a PR will be made
to merge the translations into Sunshine.}
* Use the string in the Vue component.
```html
<template>
<div>
<p>{{ $t('index.welcome') }}</p>
</div>
</template>
```
@tip{More formatting examples can be found in the
[Vue I18n guide](https://kazupon.github.io/vue-i18n/guide/formatting.html).}
##### C++
There should be minimal cases where strings need to be extracted from C++ source code; however it may be necessary in
some situations. For example the system tray icon could be localized as it is user interfacing.
* Wrap the string to be extracted in a function as shown.
```cpp
#include <boost/locale.hpp>
#include <string>
std::string msg = boost::locale::translate("Hello world!");
```
@tip{More examples can be found in the documentation for
[boost locale](https://www.boost.org/doc/libs/1_70_0/libs/locale/doc/html/messages_formatting.html).}
@warning{The below is for information only. Contributors should never include manually updated template files, or
manually compiled language files in Pull Requests.}
Strings are automatically extracted from the code to the `locale/sunshine.po` template file. The generated file is
used by CrowdIn to generate language specific template files. The file is generated using the
`.github/workflows/localize.yml` workflow and is run on any push event into the `master` branch. Jobs are only run if
any of the following paths are modified.
```yaml
- 'src/**'
```
When testing locally it may be desirable to manually extract, initialize, update, and compile strings. Python is
required for this, along with the python dependencies in the `./scripts/requirements.txt` file. Additionally,
[xgettext](https://www.gnu.org/software/gettext) must be installed.
* Extract, initialize, and update
```bash
python ./scripts/_locale.py --extract --init --update
```
* Compile
```bash
python ./scripts/_locale.py --compile
```
@attention{Due to the integration with CrowdIn, it is important to not include any extracted or compiled files in
Pull Requests. The files are automatically generated and updated by the workflow. Once the PR is merged, the
translations can take place on [CrowdIn][crowdin-url]. Once the translations are
complete, a PR will be made to merge the translations into Sunshine.}
### Testing
#### Clang Format
Source code is tested against the `.clang-format` file for linting errors. The workflow file responsible for clang
format testing is `.github/workflows/cpp-clang-format-lint.yml`.
Option 1:
```bash
find ./ -iname *.cpp -o -iname *.h -iname *.m -iname *.mm | xargs clang-format -i
```
Option 2 (will modify files):
```bash
python ./scripts/update_clang_format.py
```
#### Unit Testing
Sunshine uses [Google Test](https://github.com/google/googletest) for unit testing. Google Test is included in the
repo as a submodule. The test sources are located in the `./tests` directory.
The tests need to be compiled into an executable, and then run. The tests are built using the normal build process, but
can be disabled by setting the `BUILD_TESTS` CMake option to `OFF`.
To run the tests, execute the following command.
```bash
./build/tests/test_sunshine
```
To see all available options, run the tests with the `--help` flag.
```bash
./build/tests/test_sunshine --help
```
@tip{See the googletest [FAQ](https://google.github.io/googletest/faq.html) for more information on how to use
Google Test.}
We use [gcovr](https://www.gcovr.com) to generate code coverage reports,
and [Codecov](https://about.codecov.io) to analyze the reports for all PRs and commits.
Codecov will fail a PR if the total coverage is reduced too much, or if not enough of the diff is covered by tests.
In some cases, the code cannot be covered when running the tests inside of GitHub runners. For example, any test that
needs access to the GPU will not be able to run. In these cases, the coverage can be omitted by adding comments to the
code. See the [gcovr documentation](https://gcovr.com/en/stable/guide/exclusion-markers.html#exclusion-markers) for
more information.
Even if your changes cannot be covered in the CI, we still encourage you to write the tests for them. This will allow
maintainers to run the tests locally.
[crowdin-url]: https://translate.lizardbyte.dev
<div class="section_buttons">
| Previous | Next |
|:------------------------|-------------------------------------------------------------:|
| [Building](building.md) | [Source Code](../third-party/doxyconfig/docs/source_code.md) |
</div>

95
docs/doxygen/header.html
View File

@ -1,95 +0,0 @@
<!-- HTML header for doxygen 1.10.0-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
<!--PROJECT_ICON is not available with DOXYGEN < 1.10.0, so use the filename directly-->
<link rel="icon" href="$relpath^sunshine.ico" type="image/x-icon" />
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN FULL_SIDEBAR-->
<script type="text/javascript">var page_layout=1;</script>
<!--END FULL_SIDEBAR-->
<!--END DISABLE_INDEX-->
<script type="text/javascript" src="$relpath^jquery.js"></script>
<script type="text/javascript" src="$relpath^dynsections.js"></script>
$treeview
$search
$mathjax
$darkmode
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
$extrastylesheet
<!--DOXYGEN-AWESOME START-->
<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">
DoxygenAwesomeDarkModeToggle.init()
</script>
<script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
<script type="text/javascript">
DoxygenAwesomeFragmentCopyButton.init()
</script>
<script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
<script type="text/javascript">
DoxygenAwesomeParagraphLink.init()
</script>
<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
<script type="text/javascript">
DoxygenAwesomeInteractiveToc.init()
</script>
<!--DOXYGEN-AWESOME END-->
</head>
<body>
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN FULL_SIDEBAR-->
<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
<!--END FULL_SIDEBAR-->
<!--END DISABLE_INDEX-->
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!--BEGIN TITLEAREA-->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<!--BEGIN PROJECT_LOGO-->
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
<!--END PROJECT_LOGO-->
<!--BEGIN PROJECT_NAME-->
<td id="projectalign">
<div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
</div>
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
</td>
<!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME-->
<!--BEGIN PROJECT_BRIEF-->
<td>
<div id="projectbrief">$projectbrief</div>
</td>
<!--END PROJECT_BRIEF-->
<!--END !PROJECT_NAME-->
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN SEARCHENGINE-->
<!--BEGIN !FULL_SIDEBAR-->
<td>$searchbox</td>
<!--END !FULL_SIDEBAR-->
<!--END SEARCHENGINE-->
<!--END DISABLE_INDEX-->
</tr>
<!--BEGIN SEARCHENGINE-->
<!--BEGIN FULL_SIDEBAR-->
<tr><td colspan="2">$searchbox</td></tr>
<!--END FULL_SIDEBAR-->
<!--END SEARCHENGINE-->
</tbody>
</table>
</div>
<!--END TITLEAREA-->
<!-- end header part -->

12
docs/environment.yml
View File

@ -1,12 +0,0 @@
---
name: RTD
channels:
- conda-forge
- defaults
dependencies:
- doxygen=1.10.0
- graphviz=11.0.0
- pip
- python=3.11
- pip:
- -r ./requirements.txt

31
docs/gamestream_migration.md Normal file
View File

@ -0,0 +1,31 @@
# GameStream Migration
Nvidia announced that their GameStream service for Nvidia Games clients will be discontinued in February 2023.
Luckily, Sunshine performance is now equal to or better than Nvidia GameStream.
## Migration
We have developed a simple migration tool to help you migrate your GameStream games and apps to Sunshine automatically.
Please check out our [GSMS](https://github.com/LizardByte/GSMS) project if you're interested in an automated
migration option. GSMS offers the ability to migrate your custom and auto-detected games and apps. The
working directory, command, and image are all set in Sunshine's `apps.json` file. The box-art image is also copied
to a specified directory.
## Internet Streaming
If you are using the Moonlight Internet Hosting Tool, you can remove it from your system when you migrate to Sunshine.
To stream over the Internet with Sunshine and a UPnP-capable router, enable the UPnP option in the Sunshine Web UI.
@note{Running Sunshine together with versions of the Moonlight Internet Hosting Tool prior to v5.6 will cause UPnP
port forwarding to become unreliable. Either uninstall the tool entirely or update it to v5.6 or later.}
## Limitations
Sunshine does have some limitations, as compared to Nvidia GameStream.
* Automatic game/application list.
* Changing game settings automatically, to optimize streaming.
<div class="section_buttons">
| Previous | Next |
|:------------------------------------------------|------------------:|
| [Third-party Packages](third_party_packages.md) | [Legal](legal.md) |
</div>

571
docs/getting_started.md Normal file
View File

@ -0,0 +1,571 @@
# Getting Started
The recommended method for running Sunshine is to use the [binaries](#binaries) included in the
[latest release][latest-release], unless otherwise specified.
[Pre-releases](https://github.com/LizardByte/Sunshine/releases) are also available. These should be considered beta,
and release artifacts may be missing when merging changes on a faster cadence.
## Binaries
Binaries of Sunshine are created for each release. They are available for Linux, macOS, and Windows.
Binaries can be found in the [latest release][latest-release].
@tip{Some third party packages also exist.
See [Third Party Packages](third_party_packages.md) for more information.
No support will be provided for third party packages!}
## Install
### Docker
@warning{The Docker images are not recommended for most users.}
Docker images are available on [Dockerhub.io](https://hub.docker.com/repository/docker/lizardbyte/sunshin)
and [ghcr.io](https://github.com/orgs/LizardByte/packages?repo_name=sunshine).
See [Docker](../DOCKER_README.md) for more information.
### Linux
**CUDA Compatibility**
CUDA is used for NVFBC capture.
@tip{See [CUDA GPUS](https://developer.nvidia.com/cuda-gpus) to cross-reference Compute Capability to your GPU.}
<table>
<caption>CUDA Compatibility</caption>
<tr>
<th>CUDA Version</th>
<th>Min Driver</th>
<th>CUDA Compute Capabilities</th>
<th>Package</th>
</tr>
<tr>
<td rowspan="3">11.8.0</td>
<td rowspan="3">450.80.02</td>
<td rowspan="3">35;50;52;60;61;62;70;75;80;86;90</td>
<td>sunshine.AppImage</td>
</tr>
<tr>
<td>sunshine-ubuntu-22.04-{arch}.deb</td>
</tr>
<tr>
<td>sunshine-ubuntu-24.04-{arch}.deb</td>
</tr>
<tr>
<td rowspan="2">12.0.0</td>
<td rowspan="4">525.60.13</td>
<td rowspan="4">50;52;60;61;62;70;75;80;86;90</td>
<td>sunshine_{arch}.flatpak</td>
</tr>
<tr>
<td>sunshine-debian-bookworm-{arch}.deb</td>
</tr>
<tr>
<td>12.4.0</td>
<td>sunshine-fedora-39-{arch}.rpm</td>
</tr>
<tr>
<td>12.5.1</td>
<td>sunshine.pkg.tar.zst</td>
</tr>
<tr>
<td>n/a</td>
<td>n/a</td>
<td>n/a</td>
<td>sunshine-fedora-40-{arch}.rpm</td>
</tr>
</table>
#### AppImage
@caution{Use distro-specific packages instead of the AppImage if they are available.}
According to AppImageLint the supported distro matrix of the AppImage is below.
- ✖ Debian bullseye
- ✔ Debian bookworm
- ✔ Debian trixie
- ✔ Debian sid
- ✔ Ubuntu noble
- ✔ Ubuntu jammy
- ✖ Ubuntu focal
- ✖ Ubuntu bionic
- ✖ Ubuntu xenial
- ✖ Ubuntu trusty
- ✖ CentOS 7
##### Install
1. Download [sunshine.AppImage](https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.AppImage)
into your home directory.
```bash
cd ~
wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.AppImage
```
2. Open terminal and run the following command.
```bash
./sunshine.AppImage --install
```
##### Run
```bash
./sunshine.AppImage --install && ./sunshine.AppImage
```
##### Uninstall
```bash
./sunshine.AppImage --remove
```
#### ArchLinux
@warning{We do not provide support for any AUR packages.}
##### Install Prebuilt Packages
Follow the instructions at LizardByte's [pacman-repo](https://github.com/LizardByte/pacman-repo) to add
the repository. Then run the following command.
```bash
pacman -S sunshine
```
##### Install PKGBUILD Archive
Open terminal and run the following command.
```bash
wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.pkg.tar.gz
tar -xvf sunshine.pkg.tar.gz
cd sunshine
# install optional dependencies
pacman -S cuda # Nvidia GPU encoding support
pacman -S libva-mesa-driver # AMD GPU encoding support
makepkg -si
```
##### Uninstall
```bash
pacman -R sunshine
```
#### Debian/Ubuntu
##### Install
Download `sunshine-{distro}-{distro-version}-{arch}.deb` and run the following command.
```bash
sudo dpkg -i ./sunshine-{distro}-{distro-version}-{arch}.deb
```
@note{The `{distro-version}` is the version of the distro we built the package on. The `{arch}` is the
architecture of your operating system.}
@tip{You can double-click the deb file to see details about the package and begin installation.}
##### Uninstall
```bash
sudo apt remove sunshine
```
#### Fedora
##### Install
1. Add `rpmfusion` repositories.
```bash
sudo dnf install \
https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
```
2. Download `sunshine-{distro}-{distro-version}-{arch}.rpm` and run the following command.
```bash
sudo dnf install ./sunshine-{distro}-{distro-version}-{arch}.rpm
```
@note{The `{distro-version}` is the version of the distro we built the package on. The `{arch}` is the
architecture of your operating system.}
@tip{You can double-click the rpm file to see details about the package and begin installation.}
##### Uninstall
```bash
sudo dnf remove sunshine
```
#### Flatpak
@caution{Use distro-specific packages instead of the Flatpak if they are available.}
@important{The instructions provided here are for the version supplied in the [latest release][latest-release],
which does not necessarily match the version in the Flathub repository!}
Using this package requires that you have [Flatpak](https://flatpak.org/setup) installed.
##### Download
1. Download `sunshine_{arch}.flatpak` and run the following command.
@note{Replace `{arch}` with your system architecture.}
##### Install (system level)
```bash
flatpak install --system ./sunshine_{arch}.flatpak
```
##### Install (user level)
```bash
flatpak install --user ./sunshine_{arch}.flatpak
```
##### Additional installation (required)
```bash
flatpak run --command=additional-install.sh dev.lizardbyte.app.Sunshine
```
##### Run with NVFBC capture (X11 Only)
```bash
flatpak run dev.lizardbyte.app.Sunshine
```
##### Run with KMS capture (Wayland & X11)
```bash
sudo -i PULSE_SERVER=unix:$(pactl info | awk '/Server String/{print$3}') flatpak run dev.lizardbyte.app.Sunshine
```
##### Uninstall
```bash
flatpak run --command=remove-additional-install.sh dev.lizardbyte.app.Sunshine
flatpak uninstall --delete-data dev.lizardbyte.app.Sunshine
```
#### Homebrew
@important{The Homebrew package is experimental on Linux.}
This package requires that you have [Homebrew](https://docs.brew.sh/Installation) installed.
##### Install
```bash
brew tap LizardByte/homebrew
brew install sunshine
```
##### Uninstall
```bash
brew uninstall sunshine
```
### macOS
@important{Sunshine on macOS is experimental. Gamepads do not work.}
#### Homebrew
This package requires that you have [Homebrew](https://docs.brew.sh/Installation) installed.
##### Install
```bash
brew tap LizardByte/homebrew
brew install sunshine
```
##### Uninstall
```bash
brew uninstall sunshine
```
#### Portfile
This package requires that you have [MacPorts](https://www.macports.org/install.php) installed.
##### Install
1. Update the Macports sources.
```bash
sudo nano /opt/local/etc/macports/sources.conf
```
Add this line, replacing your username, below the line that starts with `rsync`.
```bash
file:///Users/<username>/ports
```
`Ctrl+x`, then `Y` to exit and save changes.
2. Download and install by running the following commands.
```bash
mkdir -p ~/ports/multimedia/sunshine
cd ~/ports/multimedia/sunshine
curl -OL https://github.com/LizardByte/Sunshine/releases/latest/download/Portfile
cd ~/ports
portindex
sudo port install sunshine
```
##### Install service (optional)
```bash
sudo port load sunshine
```
##### Uninstall
```bash
sudo port uninstall sunshine
```
### Windows
#### Installer (recommended)
1. Download and install
[sunshine-windows-installer.exe](https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine-windows-installer.exe)
@attention{You should carefully select or unselect the options you want to install. Do not blindly install or
enable features.}
To uninstall, find Sunshine in the list <a href="ms-settings:installed-apps">here</a> and select "Uninstall" from the
overflow menu. Different versions of Windows may provide slightly different steps for uninstall.
#### Standalone (lite version)
@warning{By using this package instead of the installer, performance will be reduced. This package is not
recommended for most users. No support will be provided!}
1. Download and extract
[sunshine-windows-portable.zip](https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine-windows-portable.zip)
2. Open command prompt as administrator
3. Firewall rules
Install:
```bash
cd /d {path to extracted directory}
scripts/add-firewall-rule.bat
```
Uninstall:
```bash
cd /d {path to extracted directory}
scripts/delete-firewall-rule.bat
```
4. Virtual Gamepad Support
Install:
```bash
cd /d {path to extracted directory}
scripts/install-gamepad.bat
```
Uninstall:
```bash
cd /d {path to extracted directory}
scripts/uninstall-gamepad.bat
```
5. Windows service
Install:
```bash
cd /d {path to extracted directory}
scripts/install-service.bat
scripts/autostart-service.bat
```
Uninstall:
```bash
cd /d {path to extracted directory}
scripts/uninstall-service.bat
```
To uninstall, delete the extracted directory which contains the `sunshine.exe` file.
## Initial Setup
After installation, some initial setup is required.
### Linux
#### KMS Capture
@warning{Capture of most Wayland-based desktop environments will fail unless this step is performed.}
@note{`cap_sys_admin` may as well be root, except you don't need to be root to run the program. This is necessary to
allow Sunshine to use KMS capture.}
##### Enable
```bash
sudo setcap cap_sys_admin+p $(readlink -f $(which sunshine))
```
#### X11 Capture
For X11 capture to work, you may need to disable the capabilities that were set for KMS capture.
```bash
sudo setcap -r $(readlink -f $(which sunshine))
```
#### Service
**Start once**
```bash
systemctl --user start sunshine
```
**Start on boot**
```bash
systemctl --user enable sunshine
```
### macOS
The first time you start Sunshine, you will be asked to grant access to screen recording and your microphone.
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).
@note{Command Keys are not forwarded by Moonlight. Right Option-Key is mapped to CMD-Key.}
@caution{Gamepads are not currently supported.}
## Usage
### Basic usage
If Sunshine is not installed/running as a service, then start Sunshine with the following command, unless a start
command is listed in the specified package [install](#install) instructions above.
@note{A service is a process that runs in the background. This is the default when installing Sunshine from the
Windows installer. Running multiple instances of Sunshine is not advised.}
```bash
sunshine
```
### Specify config file
```bash
sunshine <directory of conf file>/sunshine.conf
```
@note{You do not need to specify a config file. If no config file is entered the default location will be used.}
@attention{The configuration file specified will be created if it doesn't exist.}
### Start Sunshine over SSH (Linux/X11)
Assuming you are already logged into the host, you can use this command
```bash
ssh <user>@<ip_address> 'export DISPLAY=:0; sunshine'
```
If you are logged into the host with only a tty (teletypewriter), you can use `startx` to start the X server prior to
executing Sunshine. You nay need to add `sleep` between `startx` and `sunshine` to allow more time for the display to
be ready.
```bash
ssh <user>@<ip_address> 'startx &; export DISPLAY=:0; sunshine'
```
@tip{You could also utilize the `~/.bash_profile` or `~/.bashrc` files to set up the `DISPLAY` variable.}
@seealso{ See [Remote SSH Headless Setup](md_docs_2guides.html#remote-ssh-headless-setup)
on how to set up a headless streaming server without autologin and dummy plugs (X11 + NVidia GPUs)}
### Configuration
Sunshine is configured via the web ui, which is available on [https://localhost:47990](https://localhost:47990)
by default. You may replace *localhost* with your internal ip address.
@attention{Ignore any warning given by your browser about "insecure website". This is due to the SSL certificate
being self-signed.}
@caution{If running for the first time, make sure to note the username and password that you created.}
1. Add games and applications.
2. Adjust any configuration settings as needed.
3. In Moonlight, you may need to add the PC manually.
4. When Moonlight requests for you insert the pin:
- Login to the web ui
- Go to "PIN" in the Navbar
- Type in your PIN and press Enter, you should get a Success Message
- In Moonlight, select one of the Applications listed
### Arguments
To get a list of available arguments, run the following command.
@tabs{
@tab{ General | @code{.bash}
sunshine --help
@endcode }
@tab{ AppImage | @code{.bash}
./sunshine.AppImage --help
@endcode }
@tab{ Flatpak | @code{.bash}
flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --help
@endcode }
}
### Shortcuts
All shortcuts start with `Ctrl+Alt+Shift`, just like Moonlight.
* `Ctrl+Alt+Shift+N`: Hide/Unhide the cursor (This may be useful for Remote Desktop Mode for Moonlight)
* `Ctrl+Alt+Shift+F1/F12`: Switch to different monitor for Streaming
### Application List
* Applications should be configured via the web UI
* A basic understanding of working directories and commands is required
* You can use Environment variables in place of values
* `$(HOME)` will be replaced by the value of `$HOME`
* `$$` will be replaced by `$`, e.g. `$$(HOME)` will be become `$(HOME)`
* `env` - Adds or overwrites Environment variables for the commands/applications run by Sunshine.
This can only be changed by modifying the `apps.json` file directly.
### Considerations
* On Windows, Sunshine uses the Desktop Duplication API which only supports capturing from the GPU used for display.
If you want to capture and encode on the eGPU, connect a display or HDMI dummy display dongle to it and run the games
on that display.
* When an application is started, if there is an application already running, it will be terminated.
* If any of the prep-commands fail, starting the application is aborted.
* When the application has been shutdown, the stream shuts down as well.
* For example, if you attempt to run `steam` as a `cmd` instead of `detached` the stream will immediately fail.
This is due to the method in which the steam process is executed. Other applications may behave similarly.
* This does not apply to `detached` applications.
* The "Desktop" app works the same as any other application except it has no commands. It does not start an application,
instead it simply starts a stream. If you removed it and would like to get it back, just add a new application with
the name "Desktop" and "desktop.png" as the image path.
* For the Linux flatpak you must prepend commands with `flatpak-spawn --host`.
### HDR Support
Streaming HDR content is officially supported on Windows hosts and experimentally supported for Linux hosts.
* General HDR support information and requirements:
* HDR must be activated in the host OS, which may require an HDR-capable display or EDID emulator dongle
connected to your host PC.
* You must also enable the HDR option in your Moonlight client settings, otherwise the stream will be SDR
(and probably overexposed if your host is HDR).
* A good HDR experience relies on proper HDR display calibration both in the OS and in game. HDR calibration can
differ significantly between client and host displays.
* You may also need to tune the brightness slider or HDR calibration options in game to the different HDR brightness
capabilities of your client's display.
* Some GPUs video encoders can produce lower image quality or encoding performance when streaming in HDR compared
to SDR.
* Additional information:
@tabs{
@tab{ Windows |
- HDR streaming is supported for Intel, AMD, and NVIDIA GPUs that support encoding HEVC Main 10 or AV1 10-bit profiles.
- We recommend calibrating the display by streaming the Windows HDR Calibration app to your client device and saving an HDR calibration profile to use while streaming.
- Older games that use NVIDIA-specific NVAPI HDR rather than native Windows HDR support may not display properly in HDR.
}
@tab{ Linux |
- HDR streaming is supported for Intel and AMD GPUs that support encoding HEVC Main 10 or AV1 10-bit profiles using VAAPI.
- The KMS capture backend is required for HDR capture. Other capture methods, like NvFBC or X11, do not support HDR.
- You will need a desktop environment with a compositor that supports HDR rendering, such as Gamescope or KDE Plasma 6.
@seealso{[Arch wiki on HDR Support for Linux](https://wiki.archlinux.org/title/HDR_monitor_support) and
[Reddit Guide for HDR Support for AMD GPUs](https://www.reddit.com/r/linux_gaming/comments/10m2gyx/guide_alpha_test_hdr_on_linux)}
}
}
### Tutorials and Guides
Tutorial videos are available [here](https://www.youtube.com/playlist?list=PLMYr5_xSeuXAbhxYHz86hA1eCDugoxXY0).
Guides are available [here](guides.md).
@admonition{Community! |
Tutorials and Guides are community generated. Want to contribute? Reach out to us on our discord server.}
<div class="section_buttons">
| Previous | Next |
|:-------------------------|--------------------------:|
| [Overview](../README.md) | [Changelog](changelog.md) |
</div>
[latest-release]: https://github.com/LizardByte/Sunshine/releases/latest

534
docs/guides.md Normal file
View File

@ -0,0 +1,534 @@
# Guides
@admonition{Community | This collection of guides is written by the community!
Feel free to contribute your own tips and trips by making a PR.}
## Linux
### Discord call cancellation
| Author | [RickAndTired](https://github.com/RickAndTired) |
|------------|-------------------------------------------------|
| Difficulty | Easy |
* Set your normal *Sound Output* volume to 100%
![](images/discord_calls_01.png)
* Start Sunshine
* Set *Sound Output* to *sink-sunshine-stereo* (if it isn't automatic)
![](images/discord_calls_02.png)
* In Discord, right click *Deafen* and select your normal *Output Device*.
This is also where you will need to adjust output volume for Discord calls
![](images/discord_calls_03.png)
* Open *qpwgraph*
![](images/discord_calls_04.png)
* Connect `sunshine [sunshine-record]` to your normal *Output Device*
* Drag `monitor_FL` to `playback_FL`
* Drag `monitor_FR` to `playback_FR`
![](images/discord_calls_05.png)
### Remote SSH Headless Setup
| Author | [Eric Dong](https://github.com/e-dong) |
|------------|----------------------------------------|
| Difficulty | Intermediate |
This is a guide to setup remote SSH into host to startup X server and Sunshine without physical login and dummy plug.
The virtual display is accelerated by the NVidia GPU using the TwinView configuration.
@attention{This guide is specific for Xorg and NVidia GPUs. I start the X server using the `startx` command.
I also only tested this on an Artix runit init system on LAN.
I didn't have to do anything special with pulseaudio (pipewire untested).
Keep your monitors plugged in until the [Checkpoint](#checkpoint) step.}
@tip{Prior to editing any system configurations, you should make a copy of the original file.
This will allow you to use it for reference or revert your changes easily.}
#### The Big Picture
Once you are done, you will need to perform these 3 steps:
1. Turn on the host machine
2. Start Sunshine on remote host with a script that:
* Edits permissions of `/dev/uinput` (added sudo config to execute script with no password prompt)
* Starts X server with `startx` on virtual display
* Starts Sunshine
3. Startup Moonlight on the client of interest and connect to host
@hint{As an alternative to SSH...
**Step 2** can be replaced with autologin and starting Sunshine as a service or putting
`sunshine &` in your `.xinitrc` file if you start your X server with `startx`.
In this case, the workaround for `/dev/uinput` permissions is not needed because the udev rule would be triggered
for "physical" login. See [Linux Setup](md_docs_2getting__started.html#linux). I personally think autologin compromises
the security of the PC, so I went with the remote SSH route. I use the PC more than for gaming, so I don't need a
virtual display everytime I turn on the PC (E.g running updates, config changes, file/media server).}
First we will [setup the host](#host-setup) and then the [SSH Client](#ssh-client-setup)
(Which may not be the same as the machine running the moonlight client).
#### Host Setup
We will be setting up:
1. [Static IP Setup](#static-ip-setup)
2. [SSH Server Setup](#ssh-server-setup)
3. [Virtual Display Setup](#virtual-display-setup)
4. [Uinput Permissions Workaround](#uinput-permissions-workaround)
5. [Stream Launcher Script](#stream-launcher-script)
#### Static IP Setup
Setup static IP Address for host. For LAN connections you can use DHCP reservation within your assigned range.
e.g. 192.168.x.x. This will allow you to ssh to the host consistently, so the assigned IP address does
not change. It is preferred to set this through your router config.
#### SSH Server Setup
@note{Most distros have OpenSSH already installed. If it is not present, install OpenSSH using your package manager.}
@tabs{
@tab{Debian based | ```bash
sudo apt update
sudo apt install openssh-server
```}
@tab{Arch based | ```bash
sudo pacman -S openssh
# Install openssh-<other_init> if you are not using SystemD
# e.g. sudo pacman -S openssh-runit
```}
@tab{Alpine based | ```bash
sudo apk update
sudo apk add openssh
```}
@tab{Fedora based (dnf) | ```bash
sudo dnf install openssh-server
```}
@tab{Fedora based (yum) | ```bash
sudo yum install openssh-server
```}
}
Next make sure the OpenSSH daemon is enabled to run when the system starts.
@tabs{
@tab{SystemD | ```bash
sudo systemctl enable sshd.service
sudo systemctl start sshd.service # Starts the service now
sudo systemctl status sshd.service # See if the service is running
```}
@tab{Runit | ```bash
sudo ln -s /etc/runit/sv/sshd /run/runit/service # Enables the OpenSSH daemon to run when system starts
sudo sv start sshd # Starts the service now
sudo sv status sshd # See if the service is running
```}
@tab{OpenRC | ```bash
rc-update add sshd # Enables service
rc-status # List services to verify sshd is enabled
rc-service sshd start # Starts the service now
```}
}
**Disabling PAM in sshd**
I noticed when the ssh session is disconnected for any reason, `pulseaudio` would disconnect.
This is due to PAM handling sessions. When running `dmesg`, I noticed `elogind` would say removed user session.
In this [Gentoo Forums post](https://forums.gentoo.org/viewtopic-t-1090186-start-0.html),
someone had a similar issue. Starting the X server in the background and exiting out of the console would cause your
session to be removed.
@caution{According to this [article](https://devicetests.com/ssh-usepam-security-session-status)
disabling PAM increases security, but reduces certain functionality in terms of session handling.
*Do so at your own risk!*}
Edit the ``sshd_config`` file with the following to disable PAM.
```txt
usePAM no
```
After making changes to the `sshd_config`, restart the sshd service for changes to take effect.
@tip{Run the command to check the ssh configuration prior to restarting the sshd service.
```bash
sudo sshd -t -f /etc/ssh/sshd_config
```
An incorrect configuration will prevent the sshd service from starting, which might mean
losing SSH access to the server.}
@tabs{
@tab{SystemD | ```bash
sudo systemctl restart sshd.service
```}
@tab{Runit | ```bash
sudo sv restart sshd
```}
@tab{OpenRC | ```bash
sudo rc-service sshd restart
```}
}
#### Virtual Display Setup
As an alternative to a dummy dongle, you can use this config to create a virtual display.
@important{This is only available for NVidia GPUs using Xorg.}
@hint{Use ``xrandr`` to see name of your active display output. Usually it starts with ``DP`` or ``HDMI``. For me, it is ``DP-0``.
Put this name for the ``ConnectedMonitor`` option under the ``Device`` section.
```bash
xrandr | grep " connected" | awk '{ print $1 }'
```
}
```xorg
Section "ServerLayout"
Identifier "TwinLayout"
Screen 0 "metaScreen" 0 0
EndSection
Section "Monitor"
Identifier "Monitor0"
Option "Enable" "true"
EndSection
Section "Device"
Identifier "Card0"
Driver "nvidia"
VendorName "NVIDIA Corporation"
Option "MetaModes" "1920x1080"
Option "ConnectedMonitor" "DP-0"
Option "ModeValidation" "NoDFPNativeResolutionCheck,NoVirtualSizeCheck,NoMaxPClkCheck,NoHorizSyncCheck,NoVertRefreshCheck,NoWidthAlignmentCheck"
EndSection
Section "Screen"
Identifier "metaScreen"
Device "Card0"
Monitor "Monitor0"
DefaultDepth 24
Option "TwinView" "True"
SubSection "Display"
Modes "1920x1080"
EndSubSection
EndSection
```
@note{The `ConnectedMonitor` tricks the GPU into thinking a monitor is connected,
even if there is none actually connected! This allows a virtual display to be created that is accelerated with
your GPU! The `ModeValidation` option disables valid resolution checks, so you can choose any
resolution on the host!
**References**
* [issue comment on virtual-display-linux](https://github.com/dianariyanto/virtual-display-linux/issues/9#issuecomment-786389065)
* [Nvidia Documentation on Configuring TwinView](https://download.nvidia.com/XFree86/Linux-x86/270.29/README/configtwinview.html)
* [Arch Wiki Nvidia#TwinView](https://wiki.archlinux.org/title/NVIDIA#TwinView)
* [Unix Stack Exchange - How to add virtual display monitor with Nvidia proprietary driver](https://unix.stackexchange.com/questions/559918/how-to-add-virtual-monitor-with-nvidia-proprietary-driver)
}
#### Uinput Permissions Workaround
##### Steps
We can use `chown` to change the permissions from a script. Since this requires `sudo`,
we will need to update the sudo configuration to execute this without being prompted for a password.
1. Create a `sunshine-setup.sh` script to update permissions on `/dev/uinput`. Since we aren't logged into the host,
the udev rule doesn't apply.
2. Update user sudo configuration `/etc/sudoers.d/<user>` to allow the `sunshine-setup.sh`
script to be executed with `sudo`.
@note{After I setup the :ref:`udev rule <about/setup:install>` to get access to `/dev/uinput`, I noticed when I sshed
into the host without physical login, the ACL permissions on `/dev/uinput` were not changed. So I asked
[reddit](https://www.reddit.com/r/linux_gaming/comments/14htuzv/does_sshing_into_host_trigger_udev_rule_on_the).
I discovered that SSH sessions are not the same as a physical login.
I suppose it's not possible for SSH to trigger a udev rule or create a physical login session.}
##### Setup Script
This script will take care of any preconditions prior to starting up Sunshine.
Run the following to create a script named something like `sunshine-setup.sh`:
```bash
echo "chown $(id -un):$(id -gn) /dev/uinput" > sunshine-setup.sh && \
chmod +x sunshine-setup.sh
```
(**Optional**) To Ensure ethernet is being used for streaming, you can block Wi-Fi with `rfkill`.
Run this command to append the rfkill block command to the script:
```bash
echo "rfkill block $(rfkill list | grep "Wireless LAN" \
| sed 's/^\([[:digit:]]\).*/\1/')" >> sunshine-setup.sh
```
##### Sudo Configuration
We will manually change the permissions of `/dev/uinput` using `chown`.
You need to use `sudo` to make this change, so add/update the entry in `/etc/sudoers.d/${USER}`.
@danger{Do so at your own risk! It is more secure to give sudo and no password prompt to a single script,
than a generic executable like chown.}
@warning{Be very careful of messing this config up. If you make a typo, *YOU LOSE THE ABILITY TO USE SUDO*.
Fortunately, your system is not borked, you will need to login as root to fix the config.
You may want to setup a backup user / SSH into the host as root to fix the config if this happens.
Otherwise, you will need to plug your machine back into a monitor and login as root to fix this.
To enable root login over SSH edit your SSHD config, and add `PermitRootLogin yes`, and restart the SSH server.}
1. First make a backup of your `/etc/sudoers.d/${USER}` file.
```bash
sudo cp /etc/sudoers.d/${USER} /etc/sudoers.d/${USER}.backup
```
2. `cd` to the parent dir of the `sunshine-setup.sh` script.
3. Execute the following to update your sudoer config file.
```bash
echo "${USER} ALL=(ALL:ALL) ALL, NOPASSWD: $(pwd)/sunshine-setup.sh" \
| sudo tee /etc/sudoers.d/${USER}
```
These changes allow the script to use sudo without being prompted with a password.
e.g. `sudo $(pwd)/sunshine-setup.sh`
#### Stream Launcher Script
This is the main entrypoint script that will run the `sunshine-setup.sh` script, start up X server, and Sunshine.
The client will call this script that runs on the host via ssh.
##### Sunshine Startup Script
This guide will refer to this script as `~/scripts/sunshine.sh`.
The setup script will be referred as `~/scripts/sunshine-setup.sh`.
```bash
#!/bin/bash
set -e
export DISPLAY=:0
# Check existing X server
ps -e | grep X >/dev/null
[[ ${?} -ne 0 ]] && {
echo "Starting X server"
startx &>/dev/null &
[[ ${?} -eq 0 ]] && {
echo "X server started successfully"
} || echo "X server failed to start"
} || echo "X server already running"
# Check if sunshine is already running
ps -e | grep -e .*sunshine$ >/dev/null
[[ ${?} -ne 0 ]] && {
sudo ~/scripts/sunshine-setup.sh
echo "Starting Sunshine!"
sunshine > /dev/null &
[[ ${?} -eq 0 ]] && {
echo "Sunshine started successfully"
} || echo "Sunshine failed to start"
} || echo "Sunshine is already running"
# Add any other Programs that you want to startup automatically
# e.g.
# steam &> /dev/null &
# firefox &> /dev/null &
# kdeconnect-app &> /dev/null &
```
#### SSH Client Setup
We will be setting up:
1. [SSH Key Authentication Setup](#ssh-key-authentication-setup)
2. [SSH Client Script (Optional)](#ssh-client-script-optional)
##### SSH Key Authentication Setup
1. Setup your SSH keys with `ssh-keygen` and use `ssh-copy-id` to authorize remote login to your host.
Run `ssh <user>@<ip_address>` to login to your host.
SSH keys automate login so you don't need to input your password!
2. Optionally setup a `~/.ssh/config` file to simplify the `ssh` command
```txt
Host <some_alias>
Hostname <ip_address>
User <username>
IdentityFile ~/.ssh/<your_private_key>
```
Now you can use `ssh <some_alias>`.
`ssh <some_alias> <commands/script>` will execute the command or script on the remote host.
##### Checkpoint
As a sanity check, let's make sure your setup is working so far!
###### Test Steps
With your monitor still plugged into your Sunshine host PC:
1. `ssh <alias>`
2. `~/scripts/sunshine.sh`
3. `nvidia-smi`
You should see the Sunshine and Xorg processing running:
```bash
nvidia-smi
```
*Output:*
```txt
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 535.104.05 Driver Version: 535.104.05 CUDA Version: 12.2 |
|-----------------------------------------+----------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+======================+======================|
| 0 NVIDIA GeForce RTX 3070 Off | 00000000:01:00.0 On | N/A |
| 30% 46C P2 45W / 220W | 549MiB / 8192MiB | 2% Default |
| | | N/A |
+-----------------------------------------+----------------------+----------------------+
+---------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=======================================================================================|
| 0 N/A N/A 1393 G /usr/lib/Xorg 86MiB |
| 0 N/A N/A 1440 C+G sunshine 293MiB |
+---------------------------------------------------------------------------------------+
```
4. Check `/dev/uinput` permissions
```bash
ls -l /dev/uinput
```
*Output:*
```console
crw------- 1 <user> <primary_group> 10, 223 Aug 29 17:31 /dev/uinput
```
5. Connect to Sunshine host from a moonlight client
Now kill X and Sunshine by running `pkill X` on the host, unplug your monitors from your GPU, and repeat steps 1 - 5.
You should get the same result.
With this setup you don't need to modify the Xorg config regardless if monitors are plugged in or not.
```bash
pkill X
```
##### SSH Client Script (Optional)
At this point you have a working setup! For convenience, I created this bash script to automate the
startup of the X server and Sunshine on the host.
This can be run on Unix systems, or on Windows using the `git-bash` or any bash shell.
For Android/iOS you can install Linux emulators, e.g. `Userland` for Android and `ISH` for iOS.
The neat part is that you can execute one script to launch Sunshine from your phone or tablet!
```bash
#!/bin/bash
set -e
ssh_args="<user>@192.168.X.X" # Or use alias set in ~/.ssh/config
check_ssh(){
result=1
# Note this checks infinitely, you could update this to have a max # of retries
while [[ $result -ne 0 ]]
do
echo "checking host..."
ssh $ssh_args "exit 0" 2>/dev/null
result=$?
[[ $result -ne 0 ]] && {
echo "Failed to ssh to $ssh_args, with exit code $result"
}
sleep 3
done
echo "Host is ready for streaming!"
}
start_stream(){
echo "Starting sunshine server on host..."
echo "Start moonlight on your client of choice"
# -f runs ssh in the background
ssh -f $ssh_args "~/scripts/sunshine.sh &"
}
check_ssh
start_stream
exit_code=${?}
sleep 3
exit ${exit_code}
```
#### Next Steps
Congratulations, you can now stream your desktop headless! When trying this the first time,
keep your monitors close by incase something isn't working right.
@seealso{Now that you have a virtual display, you may want to automate changing the resolution
and refresh rate prior to connecting to an app. See
[Changing Resolution and Refresh Rate](md_docs_2app__examples#changing-resolution-and-refresh-rate)
for more information.}
## macOS
@todo{It's looking lonely here.}
## Windows
| Author | [BeeLeDev](https://github.com/BeeLeDev) |
|------------|-----------------------------------------|
| Difficulty | Intermediate |
### Discord call cancellation
Cancel Discord call audio with Voicemeeter (Standard)
#### Voicemeeter Configuration
1. Click "Hardware Out"
2. Set the physical device you receive audio to as your Hardware Out with MME
3. Turn on BUS A for the Virtual Input
#### Windows Configuration
1. Open the sound settings
2. Set your default Playback as Voicemeeter Input
@tip{Run audio in the background to find the device that your Virtual Input is using
(Voicemeeter In #), you will see the bar to the right of the device have green bars
going up and down. This device will be referred to as Voicemeeter Input.}
#### Discord Configuration
1. Open the settings
2. Go to Voice & Video
3. Set your Output Device as the physical device you receive audio to
@tip{It is usually the same device you set for Hardware Out in Voicemeeter.}
#### Sunshine Configuration
1. Go to Configuration
2. Go to the Audio/Video tab
3. Set Virtual Sink as Voicemeeter Input
@note{This should be the device you set as default previously in Playback.}
<div class="section_buttons">
| Previous | Next |
|:--------------------------------|--------------------------------------------:|
| [App Examples](app_examples.md) | [Performance Tuning](performance_tuning.md) |
</div>

0
docs/source/images/discord_calls_01.png → docs/images/discord_calls_01.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 27 KiB

0
docs/source/images/discord_calls_02.png → docs/images/discord_calls_02.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 39 KiB

0
docs/source/images/discord_calls_03.png → docs/images/discord_calls_03.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 27 KiB

0
docs/source/images/discord_calls_04.png → docs/images/discord_calls_04.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 94 KiB

After

Width:  |  Height:  |  Size: 94 KiB

0
docs/source/images/discord_calls_05.png → docs/images/discord_calls_05.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 95 KiB

After

Width:  |  Height:  |  Size: 95 KiB

20
docs/source/legal/legal.rst → docs/legal.md
View File

@ -1,13 +1,11 @@
Legal
=====
.. attention:: This documentation is for informational purposes only and is not intended as legal advice. If you have
any legal questions or concerns about using Sunshine, we recommend consulting with a lawyer.
# Legal
@attention{This documentation is for informational purposes only and is not intended as legal advice. If you have
any legal questions or concerns about using Sunshine, we recommend consulting with a lawyer.}
Sunshine is licensed under the GPL-3.0 license, which allows for free use and modification of the software.
The full text of the license can be reviewed `here <https://github.com/LizardByte/Sunshine/blob/master/LICENSE>`__.
The full text of the license can be reviewed [here](https://github.com/LizardByte/Sunshine/blob/master/LICENSE).
Commercial Use
--------------
## Commercial Use
Sunshine can be used in commercial applications without any limitations. This means that businesses and organizations
can use Sunshine to create and sell products or services without needing to seek permission or pay a fee.
@ -19,3 +17,11 @@ Motion Picture Experts Group (MPEG-LA) and/or any other necessary licensing requ
In summary, while Sunshine is free to use, it is the user's responsibility to ensure compliance with all applicable
licensing requirements when redistributing the software as part of a commercial offering. If you have any questions or
concerns about using Sunshine in a commercial setting, we recommend consulting with a lawyer.
<div class="section_buttons">
| Previous | Next |
|:------------------------------------------------|----------------------------------:|
| [Gamestream Migration](gamestream_migration.md) | [Configuration](configuration.md) |
</div>

36
docs/make.bat
View File

@ -1,36 +0,0 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
set "SPHINXOPTS=-W --keep-going"
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)
if "%1" == "" goto help
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% || exit /b %ERRORLEVEL%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% || exit /b %ERRORLEVEL%
:end
popd

20
docs/performance_tuning.md Normal file
View File

@ -0,0 +1,20 @@
# Performance Tuning
In addition to the options available in the [Configuration](configuration.md) section, there are a few additional
system options that can be used to help improve the performance of Sunshine.
## 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`.
## NVIDIA
Enabling *Fast Sync* in Nvidia settings may help reduce latency.
<div class="section_buttons">
| Previous | Next |
|:--------------------|--------------------------------------:|
| [Guides](guides.md) | [Troubleshooting](troubleshooting.md) |
</div>

8
docs/requirements.txt
View File

@ -1,8 +0,0 @@
furo==2024.7.18
m2r2==0.3.3.post2
rstcheck[sphinx]==6.2.4
rstfmt==0.0.14
setuptools # required by m2r2, Ubuntu 24.04 doesn't include this
Sphinx==7.2.6
sphinx-copybutton==0.5.2
sphinx_inline_tabs==2023.4.21

1880
docs/source/about/advanced_usage.rst
View File

File diff suppressed because it is too large Load Diff

1
docs/source/about/docker.rst
View File

@ -1 +0,0 @@
.. mdinclude:: ../../../DOCKER_README.md

370
docs/source/about/guides/app_examples.rst
View File

@ -1,370 +0,0 @@
App Examples
============
Since not all applications behave the same, we decided to create some examples to help you get started adding games
and applications to Sunshine.
.. attention:: Throughout these examples, any fields not shown are left blank. You can enhance your experience by
adding an image or a log file (via the ``Output`` field).
.. note:: When a working directory is not specified, it defaults to the folder where the target application resides.
Common Examples
---------------
Desktop
^^^^^^^
+----------------------+-----------------+
| **Field** | **Value** |
+----------------------+-----------------+
| Application Name | ``Desktop`` |
+----------------------+-----------------+
| Image | ``desktop.png`` |
+----------------------+-----------------+
Steam Big Picture
^^^^^^^^^^^^^^^^^
.. note:: Steam is launched as a detached command because Steam starts with a process that self updates itself and the original
process is killed.
.. tab:: Linux
+----------------------+------------------------------------------+
| Application Name | ``Steam Big Picture`` |
+----------------------+------------------------------------------+
| Detached Commands | ``setsid steam steam://open/bigpicture`` |
+----------------------+------------------------------------------+
| Image | ``steam.png`` |
+----------------------+------------------------------------------+
.. tab:: macOS
+----------------------+----------------------------------+
| Application Name | ``Steam Big Picture`` |
+----------------------+----------------------------------+
| Detached Commands | ``open steam://open/bigpicture`` |
+----------------------+----------------------------------+
| Image | ``steam.png`` |
+----------------------+----------------------------------+
.. tab:: Windows
+----------------------+-----------------------------+
| Application Name | ``Steam Big Picture`` |
+----------------------+-----------------------------+
| Command | ``steam://open/bigpicture`` |
+----------------------+-----------------------------+
| Image | ``steam.png`` |
+----------------------+-----------------------------+
Epic Game Store game
^^^^^^^^^^^^^^^^^^^^
.. note:: Using URI method will be the most consistent between various games.
URI (Epic)
""""""""""
.. tab:: Windows
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| Command | ``com.epicgames.launcher://apps/d759128018124dcabb1fbee9bb28e178%3A20729b9176c241f0b617c5723e70ec2d%3AOvenbird?action=launch&silent=true`` |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
Binary (Epic w/ working directory)
""""""""""""""""""""""""""""""""""
.. tab:: Windows
+----------------------+-----------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+-----------------------------------------------+
| Command | ``MarsEpic.exe`` |
+----------------------+-----------------------------------------------+
| Working Directory | ``C:\Program Files\Epic Games\SurvivingMars`` |
+----------------------+-----------------------------------------------+
Binary (Epic w/o working directory)
"""""""""""""""""""""""""""""""""""
.. tab:: Windows
+----------------------+--------------------------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+--------------------------------------------------------------+
| Command | ``"C:\Program Files\Epic Games\SurvivingMars\MarsEpic.exe"`` |
+----------------------+--------------------------------------------------------------+
Steam game
^^^^^^^^^^
.. note:: Using URI method will be the most consistent between various games.
URI (Steam)
"""""""""""
.. tab:: Linux
+----------------------+-------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+-------------------------------------------+
| Detached Commands | ``setsid steam steam://rungameid/464920`` |
+----------------------+-------------------------------------------+
.. tab:: macOS
+----------------------+-----------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+-----------------------------------+
| Detached Commands | ``open steam://rungameid/464920`` |
+----------------------+-----------------------------------+
.. tab:: Windows
+----------------------+------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+------------------------------+
| Command | ``steam://rungameid/464920`` |
+----------------------+------------------------------+
Binary (Steam w/ working directory)
"""""""""""""""""""""""""""""""""""
.. tab:: Linux
+----------------------+---------------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+---------------------------------------------------+
| Command | ``MarsSteam`` |
+----------------------+---------------------------------------------------+
| Working Directory | ``~/.steam/steam/SteamApps/common/Survivng Mars`` |
+----------------------+---------------------------------------------------+
.. tab:: macOS
+----------------------+---------------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+---------------------------------------------------+
| Command | ``MarsSteam`` |
+----------------------+---------------------------------------------------+
| Working Directory | ``~/.steam/steam/SteamApps/common/Survivng Mars`` |
+----------------------+---------------------------------------------------+
.. tab:: Windows
+----------------------+------------------------------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+------------------------------------------------------------------+
| Command | ``MarsSteam.exe`` |
+----------------------+------------------------------------------------------------------+
| Working Directory | ``C:\Program Files (x86)\Steam\steamapps\common\Surviving Mars`` |
+----------------------+------------------------------------------------------------------+
Binary (Steam w/o working directory)
""""""""""""""""""""""""""""""""""""
.. tab:: Linux
+----------------------+-------------------------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+-------------------------------------------------------------+
| Command | ``~/.steam/steam/SteamApps/common/Survivng Mars/MarsSteam`` |
+----------------------+-------------------------------------------------------------+
.. tab:: macOS
+----------------------+-------------------------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+-------------------------------------------------------------+
| Command | ``~/.steam/steam/SteamApps/common/Survivng Mars/MarsSteam`` |
+----------------------+-------------------------------------------------------------+
.. tab:: Windows
+----------------------+----------------------------------------------------------------------------------+
| Application Name | ``Surviving Mars`` |
+----------------------+----------------------------------------------------------------------------------+
| Command | ``"C:\Program Files (x86)\Steam\steamapps\common\Surviving Mars\MarsSteam.exe"`` |
+----------------------+----------------------------------------------------------------------------------+
Prep Commands
-------------
Changing Resolution and Refresh Rate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. tab:: Linux
.. tab:: X11
+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
| Command Preparations | Do: ``sh -c "xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}"`` |
| +--------------------------------------------------------------------------------------------------------------------------------+
| | Undo: ``xrandr --output HDMI-1 --mode 3840x2160 --rate 120`` |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
.. hint::
The above only works if the xrandr mode already exists. You will need to create new modes to stream to macOS and iOS devices, since they use non standard resolutions.
You can update the ``Do`` command to this:
.. code-block:: bash
bash -c "${HOME}/scripts/set-custom-res.sh \"${SUNSHINE_CLIENT_WIDTH}\" \"${SUNSHINE_CLIENT_HEIGHT}\" \"${SUNSHINE_CLIENT_FPS}\""
The ``set-custom-res.sh`` will have this content:
.. code-block:: bash
#!/bin/bash
# Get params and set any defaults
width=${1:-1920}
height=${2:-1080}
refresh_rate=${3:-60}
# You may need to adjust the scaling differently so the UI/text isn't too small / big
scale=${4:-0.55}
# Get the name of the active display
display_output=$(xrandr | grep " connected" | awk '{ print $1 }')
# Get the modeline info from the 2nd row in the cvt output
modeline=$(cvt ${width} ${height} ${refresh_rate} | awk 'FNR == 2')
xrandr_mode_str=${modeline//Modeline \"*\" /}
mode_alias="${width}x${height}"
echo "xrandr setting new mode ${mode_alias} ${xrandr_mode_str}"
xrandr --newmode ${mode_alias} ${xrandr_mode_str}
xrandr --addmode ${display_output} ${mode_alias}
# Reset scaling
xrandr --output ${display_output} --scale 1
# Apply new xrandr mode
xrandr --output ${display_output} --primary --mode ${mode_alias} --pos 0x0 --rotate normal --scale ${scale}
# Optional reset your wallpaper to fit to new resolution
# xwallpaper --zoom /path/to/wallpaper.png
.. tab:: Wayland
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| Command Preparations | Do: ``sh -c "wlr-xrandr --output HDMI-1 --mode \"${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}Hz\""`` |
| +-----------------------------------------------------------------------------------------------------------------------------------+
| | Undo: ``wlr-xrandr --output HDMI-1 --mode 3840x2160@120Hz`` |
+----------------------+-----------------------------------------------------------------------------------------------------------------------------------+
.. hint::
``wlr-xrandr`` only works with wlroots-based compositors.
.. tab:: Gnome (Wayland, X11)
+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
| Command Preparations | Do: ``sh -c "xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}"`` |
| +--------------------------------------------------------------------------------------------------------------------------------+
| | Undo: ``xrandr --output HDMI-1 --mode 3840x2160 --rate 120`` |
+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
The commands above are valid for an X11 session but won't work for
Wayland. In that case ``xrandr`` must be replaced by `gnome-randr.py
<https://gitlab.com/Oschowa/gnome-randr>`_. This script is intended as a
drop-in replacement with the same syntax. (It can be saved in
``/usr/local/bin`` and needs to be made executable.)
.. tab:: KDE Plasma (Wayland, X11)
+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| Command Preparations | Do: ``sh -c "kscreen-doctor output.HDMI-A-1.mode.${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}@${SUNSHINE_CLIENT_FPS}"`` |
| +-------------------------------------------------------------------------------------------------------------------------------+
| | Undo: ``kscreen-doctor output.HDMI-A-1.mode.3840x2160@120`` |
+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
.. tab:: NVIDIA
+----------------------+------------------------------------------------------------------------------------------------------+
| Command Preparations | Do: ``sh -c "${HOME}/scripts/set-custom-res.sh ${SUNSHINE_CLIENT_WIDTH} ${SUNSHINE_CLIENT_HEIGHT}"`` |
| +------------------------------------------------------------------------------------------------------+
| | Undo: ``sh -c "${HOME}/scripts/set-custom-res.sh 3840 2160"`` |
+----------------------+------------------------------------------------------------------------------------------------------+
The ``set-custom-res.sh`` will have this content:
.. code-block:: bash
#!/bin/bash
# Get params and set any defaults
width=${1:-1920}
height=${2:-1080}
output=${3:-HDMI-1}
nvidia-settings -a CurrentMetaMode="${output}: nvidia-auto-select { ViewPortIn=${width}x${height}, ViewPortOut=${width}x${height}+0+0 }"
.. tab:: macOS
.. tab:: displayplacer
.. note:: This example uses the `displayplacer` tool to change the resolution.
This tool can be installed following instructions in their
`GitHub repository <https://github.com/jakehilborn/displayplacer>`__.
+----------------------+-----------------------------------------------------------------------------------------------+
| Command Preparations | Do: ``displayplacer "id:<screenId> res:1920x1080 hz:60 scaling:on origin:(0,0) degree:0"`` |
| +-----------------------------------------------------------------------------------------------+
| | Undo: ``displayplacer "id:<screenId> res:3840x2160 hz:120 scaling:on origin:(0,0) degree:0"`` |
+----------------------+-----------------------------------------------------------------------------------------------+
.. tab:: Windows
.. tab:: QRes
.. note:: This example uses the `QRes` tool to change the resolution and refresh rate.
This tool can be downloaded from their `SourceForge repository <https://sourceforge.net/projects/qres/>`__.
+----------------------+------------------------------------------------------------------------------------------------------------------+
| Command Preparations | Do: ``cmd /C FullPath\qres.exe /x:%SUNSHINE_CLIENT_WIDTH% /y:%SUNSHINE_CLIENT_HEIGHT% /r:%SUNSHINE_CLIENT_FPS%`` |
| +------------------------------------------------------------------------------------------------------------------+
| | Undo: ``cmd /C FullPath\qres.exe /x:3840 /y:2160 /r:120`` |
+----------------------+------------------------------------------------------------------------------------------------------------------+
Additional Considerations
-------------------------
.. tab:: Linux
.. tab:: Flatpak
.. attention:: Because Flatpak packages run in a sandboxed environment and do not normally have access to the
host, the Flatpak of Sunshine requires commands to be prefixed with ``flatpak-spawn --host``.
.. tab:: Windows
**Elevating Commands (Windows)**
If you've installed Sunshine as a service (default), you can specify if a command should be elevated with
administrative privileges. Simply enable the elevated option in the WEB UI, or add it to the JSON configuration.
This is an option for both prep-cmd and regular commands and will launch the process with the current user without a
UAC prompt.
.. note:: It is important to write the values "true" and "false" as string values, not as the typical true/false
values in most JSON.
**Example**
.. code-block:: json
{
"name": "Game With AntiCheat that Requires Admin",
"output": "",
"cmd": "ping 127.0.0.1",
"exclude-global-prep-cmd": "false",
"elevated": "true",
"prep-cmd": [
{
"do": "powershell.exe -command \"Start-Streaming\"",
"undo": "powershell.exe -command \"Stop-Streaming\"",
"elevated": "false"
}
],
"image-path": ""
}

11
docs/source/about/guides/guides.rst
View File

@ -1,11 +0,0 @@
Guides
======
Collection of guides written by the community!
.. toctree::
:maxdepth: 2
app_examples
linux
windows

10
docs/source/about/guides/linux.rst
View File

@ -1,10 +0,0 @@
Linux
======
Collection of Sunshine Linux host guides.
.. toctree::
:maxdepth: 1
:glob:
linux/*

30
docs/source/about/guides/linux/discord_calls.rst
View File

@ -1,30 +0,0 @@
How to not stream Discord call audio
====================================
#. Set your normal `Sound Output` volume to 100%
.. image:: ../../../images/discord_calls_01.png
#. Start Sunshine
#. Set `Sound Output` to `sink-sunshine-stereo` (if it isn't automatic)
.. image:: ../../../images/discord_calls_02.png
#. In Discord - `Right Click` - `Deafen` - Select your normal `Output Device`
This is also where you will need to adjust output volume for Discord calls
.. image:: ../../../images/discord_calls_03.png
#. Open `qpwgraph`
.. image:: ../../../images/discord_calls_04.png
#. Connect `sunshine [sunshine-record]` to your normal `Output Device`
* Drag `monitor_FL` to `playback_FL`
* Drag `monitor_FR` to `playback_FR`
.. image:: ../../../images/discord_calls_05.png

526
docs/source/about/guides/linux/headless_ssh.rst
View File

@ -1,526 +0,0 @@
Remote SSH Headless Setup
=========================
.. csv-table:: Remote SSH Headless Setup
:header-rows: 0
:stub-columns: 1
Author, `Eric Dong <https://github.com/e-dong>`__
Difficulty, Intermediate
This is a guide to setup remote SSH into host to startup X server and sunshine without physical login and dummy plug.
The virtual display is accelerated by the NVidia GPU using the TwinView configuration.
.. attention::
This guide is specific for Xorg and NVidia GPUs. I start the X server using the ``startx`` command.
I also only tested this on an Artix runit init system on LAN.
I didn't have to do anything special with pulseaudio (pipewire untested).
Keep your monitors plugged in until the `Checkpoint`_ step
.. tip::
Prior to editing any system configurations, you should make a copy of the original file.
This will allow you to use it for reference or revert your changes easily.
The Big Picture
---------------
Once you are done, you will need to perform these 3 steps:
#. Turn on the host machine
#. Start sunshine on remote host with a script that:
- Edits permissions of ``/dev/uinput`` (added sudo config to execute script with no password prompt)
- Starts X server with ``startx`` on virtual display
- Starts ``Sunshine``
#. Startup Moonlight on the client of interest and connect to host
.. hint::
As an alternative to SSH...
**Step 2** can be replaced with autologin and starting sunshine as a service or putting
``sunshine &`` in your ``.xinitrc`` file if you start your X server with ``startx``.
In this case, the workaround for ``/dev/uinput`` permissions is not needed because the udev rule would be triggered
for "physical" login. See :ref:`Linux Setup <about/setup:install>`. I personally think autologin compromises the
security of the PC, so I went with the remote SSH route. I use the PC more than for gaming, so I don't need a
virtual display everytime I turn on the PC (E.g running updates, config changes, file/media server).
First we will setup the host and then the SSH Client (Which may not be the same as the machine running the
moonlight client)
Host Setup
----------
We will be setting up:
#. `Static IP Setup`_
#. `SSH Server Setup`_
#. `Virtual Display Setup`_
#. `Uinput Permissions Workaround`_
#. `Stream Launcher Script`_
Static IP Setup
^^^^^^^^^^^^^^^
Setup static IP Address for host. For LAN connections you can use DHCP reservation within your assigned range.
e.g. 192.168.x.x. This will allow you to ssh to the host consistently, so the assigned IP address does
not change. It is preferred to set this through your router config.
SSH Server Setup
^^^^^^^^^^^^^^^^
.. note::
Most distros have OpenSSH already installed. If it is not present, install OpenSSH using your package manager.
.. tab:: Debian/Ubuntu
.. code-block:: bash
sudo apt update
sudo apt install openssh-server
.. tab:: Arch/Artix
.. code-block:: bash
sudo pacman -S openssh
# Install openssh-<other_init> if you are not using SystemD
# e.g. sudo pacman -S openssh-runit
.. tab:: Alpine
.. code-block:: bash
sudo apk update
sudo apk add openssh
.. tab:: CentOS/RHEL/Fedora
**CentOS/RHEL 7**
.. code-block:: bash
sudo yum install openssh-server
**CentOS/Fedora/RHEL 8**
.. code-block:: bash
sudo dnf install openssh-server
Next make sure the OpenSSH daemon is enabled to run when the system starts.
.. tab:: SystemD
.. code-block:: bash
sudo systemctl enable sshd.service
sudo systemctl start sshd.service # Starts the service now
sudo systemctl status sshd.service # See if the service is running
.. tab:: Runit
.. code-block:: bash
sudo ln -s /etc/runit/sv/sshd /run/runit/service # Enables the OpenSSH daemon to run when system starts
sudo sv start sshd # Starts the service now
sudo sv status sshd # See if the service is running
.. tab:: OpenRC
.. code-block:: bash
rc-update add sshd # Enables service
rc-status # List services to verify sshd is enabled
rc-service sshd start # Starts the service now
**Disabling PAM in sshd**
I noticed when the ssh session is disconnected for any reason, ``pulseaudio`` would disconnect.
This is due to PAM handling sessions. When running ``dmesg``, I noticed ``elogind`` would say removed user session.
In this `Gentoo Forums post <https://forums.gentoo.org/viewtopic-t-1090186-start-0.html>`__,
someone had a similar issue. Starting the X server in the background and exiting out of the console would cause your
session to be removed.
.. caution::
According to this `article <https://devicetests.com/ssh-usepam-security-session-status>`__
disabling PAM increases security, but reduces certain functionality in terms of session handling.
*Do so at your own risk!*
Edit the ``sshd_config`` file with the following to disable PAM.
.. code-block:: text
usePAM no
After making changes to the ``sshd_config``, restart the sshd service for changes to take effect.
.. tip::
Run the command to check the ssh configuration prior to restarting the sshd service.
.. code-block:: bash
sudo sshd -t -f /etc/ssh/sshd_config
An incorrect configuration will prevent the sshd service from starting, which might mean
losing SSH access to the server.
.. tab:: SystemD
.. code-block:: bash
sudo systemctl restart sshd.service
.. tab:: Runit
.. code-block:: bash
sudo sv restart sshd
.. tab:: OpenRC
.. code-block:: bash
sudo rc-service sshd restart
Virtual Display Setup
^^^^^^^^^^^^^^^^^^^^^
As an alternative to a dummy dongle, you can use this config to create a virtual display.
.. important::
This is only available for NVidia GPUs using Xorg.
.. hint::
Use ``xrandr`` to see name of your active display output. Usually it starts with ``DP`` or ``HDMI``. For me, it is ``DP-0``.
Put this name for the ``ConnectedMonitor`` option under the ``Device`` section.
.. code-block:: bash
xrandr | grep " connected" | awk '{ print $1 }'
.. code-block:: xorg.conf
Section "ServerLayout"
Identifier "TwinLayout"
Screen 0 "metaScreen" 0 0
EndSection
Section "Monitor"
Identifier "Monitor0"
Option "Enable" "true"
EndSection
Section "Device"
Identifier "Card0"
Driver "nvidia"
VendorName "NVIDIA Corporation"
Option "MetaModes" "1920x1080"
Option "ConnectedMonitor" "DP-0"
Option "ModeValidation" "NoDFPNativeResolutionCheck,NoVirtualSizeCheck,NoMaxPClkCheck,NoHorizSyncCheck,NoVertRefreshCheck,NoWidthAlignmentCheck"
EndSection
Section "Screen"
Identifier "metaScreen"
Device "Card0"
Monitor "Monitor0"
DefaultDepth 24
Option "TwinView" "True"
SubSection "Display"
Modes "1920x1080"
EndSubSection
EndSection
.. note::
The ``ConnectedMonitor`` tricks the GPU into thinking a monitor is connected,
even if there is none actually connected! This allows a virtual display to be created that is accelerated with
your GPU! The ``ModeValidation`` option disables valid resolution checks, so you can choose any
resolution on the host!
**References**
- `issue comment on virtual-display-linux
<https://github.com/dianariyanto/virtual-display-linux/issues/9#issuecomment-786389065>`__
- `Nvidia Documentation on Configuring TwinView
<https://download.nvidia.com/XFree86/Linux-x86/270.29/README/configtwinview.html>`__
- `Arch Wiki Nvidia#TwinView <https://wiki.archlinux.org/title/NVIDIA#TwinView>`__
- `Unix Stack Exchange - How to add virtual display monitor with Nvidia proprietary driver
<https://unix.stackexchange.com/questions/559918/how-to-add-virtual-monitor-with-nvidia-proprietary-driver>`__
Uinput Permissions Workaround
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**Steps**
We can use ``chown`` to change the permissions from a script. Since this requires ``sudo``,
we will need to update the sudo configuration to execute this without being prompted for a password.
#. Create a ``sunshine-setup.sh`` script to update permissions on ``/dev/uinput``. Since we aren't logged into the host,
the udev rule doesn't apply.
#. Update user sudo configuration ``/etc/sudoers.d/<user>`` to allow the ``sunshine-setup.sh``
script to be executed with ``sudo``.
.. note::
After I setup the :ref:`udev rule <about/setup:install>` to get access to ``/dev/uinput``,
I noticed when I sshed into the host without physical login, the ACL permissions on ``/dev/uinput`` were not changed.
So I asked `reddit
<https://www.reddit.com/r/linux_gaming/comments/14htuzv/does_sshing_into_host_trigger_udev_rule_on_the/>`__.
I discovered that SSH sessions are not the same as a physical login.
I suppose it's not possible for SSH to trigger a udev rule or create a physical login session.
**Setup Script**
This script will take care of any preconditions prior to starting up sunshine.
Run the following to create a script named something like ``sunshine-setup.sh``:
.. code-block:: bash
echo "chown $(id -un):$(id -gn) /dev/uinput" > sunshine-setup.sh &&\
chmod +x sunshine-setup.sh
(**Optional**) To Ensure ethernet is being used for streaming,
you can block WiFi with ``rfkill``.
Run this command to append the rfkill block command to the script:
.. code-block:: bash
echo "rfkill block $(rfkill list | grep "Wireless LAN" \
| sed 's/^\([[:digit:]]\).*/\1/')" >> sunshine-setup.sh
**Sudo Configuration**
We will manually change the permissions of ``/dev/uinput`` using ``chown``.
You need to use ``sudo`` to make this change, so add/update the entry in ``/etc/sudoers.d/${USER}``
.. danger::
Do so at your own risk! It is more secure to give sudo and no password prompt to a single script,
than a generic executable like chown.
.. warning::
Be very careful of messing this config up. If you make a typo, *YOU LOSE THE ABILITY TO USE SUDO*.
Fortunately, your system is not borked, you will need to login as root to fix the config.
You may want to setup a backup user / SSH into the host as root to fix the config if this happens.
Otherwise you will need to plug your machine back into a monitor and login as root to fix this.
To enable root login over SSH edit your SSHD config, and add ``PermitRootLogin yes``, and restart the SSH server.
#. First make a backup of your ``/etc/sudoers.d/${USER}`` file.
.. code-block:: bash
sudo cp /etc/sudoers.d/${USER} /etc/sudoers.d/${USER}.backup
#. ``cd`` to the parent dir of the ``sunshine-setup.sh`` script.
#. Execute the following to update your sudoer config file.
.. code-block:: bash
echo "${USER} ALL=(ALL:ALL) ALL, NOPASSWD: $(pwd)/sunshine-setup.sh" \
| sudo tee /etc/sudoers.d/${USER}
These changes allow the script to use sudo without being prompted with a password.
e.g. ``sudo $(pwd)/sunshine-setup.sh``
Stream Launcher Script
^^^^^^^^^^^^^^^^^^^^^^
This is the main entrypoint script that will run the ``sunshine-setup.sh`` script, start up X server, and Sunshine.
The client will call this script that runs on the host via ssh.
**Sunshine Startup Script**
This guide will refer to this script as ``~/scripts/sunshine.sh``.
The setup script will be referred as ``~/scripts/sunshine-setup.sh``
.. code-block:: bash
#!/bin/bash
export DISPLAY=:0
# Check existing X server
ps -e | grep X >/dev/null
[[ ${?} -ne 0 ]] && {
echo "Starting X server"
startx &>/dev/null &
[[ ${?} -eq 0 ]] && {
echo "X server started successfully"
} || echo "X server failed to start"
} || echo "X server already running"
# Check if sunshine is already running
ps -e | grep -e .*sunshine$ >/dev/null
[[ ${?} -ne 0 ]] && {
sudo ~/scripts/sunshine-setup.sh
echo "Starting Sunshine!"
sunshine > /dev/null &
[[ ${?} -eq 0 ]] && {
echo "Sunshine started successfully"
} || echo "Sunshine failed to start"
} || echo "Sunshine is already running"
# Add any other Programs that you want to startup automatically
# e.g.
# steam &> /dev/null &
# firefox &> /dev/null &
# kdeconnect-app &> /dev/null &
----
SSH Client Setup
----------------
We will be setting up:
#. `SSH Key Authentication Setup`_
#. `SSH Client Script (Optional)`_
SSH Key Authentication Setup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#. Setup your SSH keys with ``ssh-keygen`` and use ``ssh-copy-id`` to authorize remote login to your host.
Run ``ssh <user>@<ip_address>`` to login to your host.
SSH keys automate login so you don't need to input your password!
#. Optionally setup a ``~/.ssh/config`` file to simplify the ``ssh`` command
.. code-block:: text
Host <some_alias>
Hostname <ip_address>
User <username>
IdentityFile ~/.ssh/<your_private_key>
Now you can use ``ssh <some_alias>``.
``ssh <some_alias> <commands/script>`` will execute the command or script on the remote host.
Checkpoint
^^^^^^^^^^
As a sanity check, let's make sure your setup is working so far!
**Test Steps**
With your monitor still plugged into your Sunshine host PC:
#. ``ssh <alias>``
#. ``~/scripts/sunshine.sh``
#. ``nvidia-smi``
You should see the sunshine and Xorg processing running:
.. code-block:: bash
nvidia-smi
*Output:*
.. code-block:: console
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 535.104.05 Driver Version: 535.104.05 CUDA Version: 12.2 |
|-----------------------------------------+----------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+======================+======================|
| 0 NVIDIA GeForce RTX 3070 Off | 00000000:01:00.0 On | N/A |
| 30% 46C P2 45W / 220W | 549MiB / 8192MiB | 2% Default |
| | | N/A |
+-----------------------------------------+----------------------+----------------------+
+---------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=======================================================================================|
| 0 N/A N/A 1393 G /usr/lib/Xorg 86MiB |
| 0 N/A N/A 1440 C+G sunshine 293MiB |
+---------------------------------------------------------------------------------------+
#. Check ``/dev/uinput`` permissions
.. code-block:: bash
ls -l /dev/uinput
*Output:*
.. code-block:: console
crw------- 1 <user> <primary_group> 10, 223 Aug 29 17:31 /dev/uinput
#. Connect to Sunshine host from a moonlight client
Now kill X and sunshine by running ``pkill X`` on the host,
unplug your monitors from your GPU, and repeat steps 1 - 5.
You should get the same result.
With this setup you don't need to modify the Xorg config regardless if monitors are plugged in or not.
.. code-block:: bash
pkill X
SSH Client Script (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
At this point you have a working setup! For convenience I created this bash script to automate the
startup of the X server and Sunshine on the host.
This can be run on Unix systems, or on Windows using the ``git-bash`` or any bash shell.
For Android/iOS you can install Linux emulators, e.g. ``Userland`` for Android and ``ISH`` for iOS.
The neat part is that you can execute one script to launch Sunshine from your phone or tablet!
.. code-block:: bash
#!/bin/bash
ssh_args="<user>@192.168.X.X" # Or use alias set in ~/.ssh/config
check_ssh(){
result=1
# Note this checks infinitely, you could update this to have a max # of retries
while [[ $result -ne 0 ]]
do
echo "checking host..."
ssh $ssh_args "exit 0" 2>/dev/null
result=$?
[[ $result -ne 0 ]] && {
echo "Failed to ssh to $ssh_args, with exit code $result"
}
sleep 3
done
echo "Host is ready for streaming!"
}
start_stream(){
echo "Starting sunshine server on host..."
echo "Start moonlight on your client of choice"
# -f runs ssh in the background
ssh -f $ssh_args "~/scripts/sunshine.sh &"
}
check_ssh
start_stream
exit_code=${?}
sleep 3
exit ${exit_code}
Next Steps
----------
Congrats you can now stream your desktop headless! When trying this the first time,
keep your monitors close by incase something isn't working right.
If you have any feedback and any suggestions, feel free to make a post on Discord!
.. seealso::
Now that you have a virtual display, you may want to automate changing the resolution
and refresh rate prior to connecting to an app. See :ref:`Changing Resolution and Refresh Rate
<about/guides/app_examples:changing resolution and refresh rate>` for more information.

10
docs/source/about/guides/windows.rst
View File

@ -1,10 +0,0 @@
Windows
=======
Collection of Sunshine Windows host guides.
.. toctree::
:maxdepth: 1
:glob:
windows/*

37
docs/source/about/guides/windows/discord_voicemeeter.rst
View File

@ -1,37 +0,0 @@
Discord call audio cancellation with Voicemeeter (Standard)
===========================================================
Voicemeeter
^^^^^^^^^^^
#. Click Hardware Out
#. Set the physical device you recieve audio to as your Hardware Out with MME
#. Turn on BUS A for the Virtual Input
Windows
^^^^^^^
#. Open the sound settings
#. Set your default Playback as Voicemeeter Input
.. note:: Run audio in the background to find the device that your Virtual Input is using
(Voicemeeter In #), you will see the bar to the right of the device have green bars
going up and down. This device will be referred to as Voicemeeter Input.
Discord
^^^^^^^
#. Open the settings
#. Go to Voice & Video
#. Set your Output Device as the physical you receive audio to
.. note:: It is usually the same device you set for Hardware Out in Voicemeeter.
Sunshine
^^^^^^^^
#. Go to Configuration
#. Go to the Audio/Video tab
#. Set Virtual Sink as Voicemeeter Input
.. note:: This should be the device you set as default previously in Playback.

1
docs/source/about/overview.rst
View File

@ -1 +0,0 @@
.. include:: ../../../README.rst

653
docs/source/about/setup.rst
View File

@ -1,653 +0,0 @@
Setup
=====
.. _latest release: https://github.com/LizardByte/Sunshine/releases/latest
The recommended method for running Sunshine is to use the `binaries`_ bundled with the `latest release`_.
Binaries
--------
Binaries of Sunshine are created for each release. They are available for Linux, macOS, and Windows.
Binaries can be found in the `latest release`_.
.. tip:: Some third party packages also exist. See
:ref:`Third Party Packages <about/third_party_packages:third party packages>`.
No support will be provided for third party packages!
Install
-------
.. tab:: Docker
.. warning:: The Docker images are not recommended for most users. No support will be provided!
Docker images are available on `Dockerhub.io <https://hub.docker.com/repository/docker/lizardbyte/sunshine>`__
and `ghcr.io <https://github.com/orgs/LizardByte/packages?repo_name=sunshine>`__.
See :ref:`Docker <about/docker:docker>` for additional information.
.. tab:: Linux
**CUDA Compatibility**
CUDA is used for NVFBC capture.
.. tip:: See `CUDA GPUS <https://developer.nvidia.com/cuda-gpus>`__ to cross reference Compute Capability to your GPU.
.. table::
:widths: auto
=========================================== ============== ============== ================================
Package CUDA Version Min Driver CUDA Compute Capabilities
=========================================== ============== ============== ================================
sunshine.AppImage 11.8.0 450.80.02 35;50;52;60;61;62;70;75;80;86;90
sunshine.pkg.tar.zst 11.8.0 450.80.02 35;50;52;60;61;62;70;75;80;86;90
sunshine_{arch}.flatpak 12.0.0 525.60.13 50;52;60;61;62;70;75;80;86;90
sunshine-debian-bookworm-{arch}.deb 12.0.0 525.60.13 50;52;60;61;62;70;75;80;86;90
sunshine-fedora-39-{arch}.rpm 12.4.0 525.60.13 50;52;60;61;62;70;75;80;86;90
sunshine-fedora-40-{arch}.rpm n/a n/a n/a
sunshine-ubuntu-22.04-{arch}.deb 11.8.0 450.80.02 35;50;52;60;61;62;70;75;80;86;90
sunshine-ubuntu-24.04-{arch}.deb 11.8.0 450.80.02 35;50;52;60;61;62;70;75;80;86;90
=========================================== ============== ============== ================================
.. tab:: AppImage
.. caution:: Use distro-specific packages instead of the AppImage if they are available.
According to AppImageLint the supported distro matrix of the AppImage is below.
- ✖ Debian bullseye
- ✔ Debian bookworm
- ✔ Debian trixie
- ✔ Debian sid
- ✔ Ubuntu noble
- ✔ Ubuntu jammy
- ✖ Ubuntu focal
- ✖ Ubuntu bionic
- ✖ Ubuntu xenial
- ✖ Ubuntu trusty
- ✖ CentOS 7
#. Download ``sunshine.AppImage`` to your home directory.
.. code-block:: bash
cd ~
wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.AppImage
#. Open terminal and run the following code.
.. code-block:: bash
./sunshine.AppImage --install
Start:
.. code-block:: bash
./sunshine.AppImage --install && ./sunshine.AppImage
Uninstall:
.. code-block:: bash
./sunshine.AppImage --remove
.. tab:: Arch Linux Package
.. warning:: We do not provide support for any AUR packages.
.. tab:: Prebuilt Package
#. Follow the instructions at LizardByte's `pacman-repo <https://github.com/LizardByte/pacman-repo>`__ to add
the repository. Then run the following code.
.. code-block:: bash
pacman -S sunshine
Uninstall:
.. code-block:: bash
pacman -R sunshine
.. tab:: PKGBUILD Archive
#. Open terminal and run the following code.
.. code-block:: bash
wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.pkg.tar.gz
tar -xvf sunshine.pkg.tar.gz
cd sunshine
# install optional dependencies
pacman -S cuda # Nvidia GPU encoding support
pacman -S libva-mesa-driver # AMD GPU encoding support
makepkg -si
Uninstall:
.. code-block:: bash
pacman -R sunshine
.. tab:: Debian/Ubuntu Package
#. Download ``sunshine-{distro}-{distro-version}-{arch}.deb`` and run the following code.
.. code-block:: bash
sudo dpkg -i ./sunshine-{distro}-{distro-version}-{arch}.deb
.. note:: The ``{distro-version}`` is the version of the distro we built the package on. The ``{arch}`` is the
architecture of your operating system.
.. tip:: You can double click the deb file to see details about the package and begin installation.
Uninstall:
.. code-block:: bash
sudo apt remove sunshine
.. tab:: Flatpak Package
.. caution:: Use distro-specific packages instead of the Flatpak if they are available.
.. important:: The instructions provided here are for the version supplied in the `latest release`_, which does
not necessarily match the version in the Flathub repository!
#. Install `Flatpak <https://flatpak.org/setup/>`__ as required.
#. Download ``sunshine_{arch}.flatpak`` and run the following code.
.. note:: Be sure to replace ``{arch}`` with the architecture for your operating system.
System level (recommended)
.. code-block:: bash
flatpak install --system ./sunshine_{arch}.flatpak
User level
.. code-block:: bash
flatpak install --user ./sunshine_{arch}.flatpak
Additional installation (required)
.. code-block:: bash
flatpak run --command=additional-install.sh dev.lizardbyte.app.Sunshine
Start:
X11 and NVFBC capture (X11 Only)
.. code-block:: bash
flatpak run dev.lizardbyte.app.Sunshine
KMS capture (Wayland & X11)
.. code-block:: bash
sudo -i PULSE_SERVER=unix:$(pactl info | awk '/Server String/{print$3}') \
flatpak run dev.lizardbyte.app.Sunshine
Uninstall:
.. code-block:: bash
flatpak run --command=remove-additional-install.sh dev.lizardbyte.app.Sunshine
flatpak uninstall --delete-data dev.lizardbyte.app.Sunshine
.. tab:: Homebrew
.. important:: The Homebrew package is experimental.
#. Install `Homebrew <https://docs.brew.sh/Installation>`__
#. Update the Homebrew sources and install Sunshine.
.. code-block:: bash
brew tap LizardByte/homebrew
brew install sunshine
.. tab:: RPM Package
#. Add `rpmfusion` repositories by running the following code.
.. code-block:: bash
sudo dnf install \
https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
#. Download ``sunshine-{distro}-{distro-version}-{arch}.rpm`` and run the following code.
.. code-block:: bash
sudo dnf install ./sunshine-{distro}-{distro-version}-{arch}.rpm
.. note:: The ``{distro-version}`` is the version of the distro we built the package on. The ``{arch}`` is the
architecture of your operating system.
.. tip:: You can double click the rpm file to see details about the package and begin installation.
Uninstall:
.. code-block:: bash
sudo dnf remove sunshine
The `deb`, `rpm`, `zst`, `Flatpak` and `AppImage` packages should handle the steps below automatically.
Third party packages may not.
Sunshine needs access to `uinput` to create mouse and gamepad virtual devices and (optionally) to `uhid`
in order to emulate a PS5 DualSense joypad with Gyro, Acceleration and Touchpad support.
#. Create and reload `udev` rules for `uinput` and `uhid`.
.. code-block:: bash
echo 'KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess"\nKERNEL=="uhid", TAG+="uaccess"' | \
sudo tee /etc/udev/rules.d/60-sunshine.rules
sudo udevadm control --reload-rules
sudo udevadm trigger
sudo modprobe uinput
#. Enable permissions for KMS capture.
.. warning:: Capture of most Wayland-based desktop environments will fail unless this step is performed.
.. note:: ``cap_sys_admin`` may as well be root, except you don't need to be root to run it. It is necessary to
allow Sunshine to use KMS capture.
**Enable**
.. code-block:: bash
sudo setcap cap_sys_admin+p $(readlink -f $(which sunshine))
**Disable (for Xorg/X11 only)**
.. code-block:: bash
sudo setcap -r $(readlink -f $(which sunshine))
#. Optionally, configure autostart service
- filename: ``~/.config/systemd/user/sunshine.service``
- contents:
.. code-block:: cfg
[Unit]
Description=Sunshine self-hosted game stream host for Moonlight.
StartLimitIntervalSec=500
StartLimitBurst=5
[Service]
ExecStart=<see table>
Restart=on-failure
RestartSec=5s
#Flatpak Only
#ExecStop=flatpak kill dev.lizardbyte.app.Sunshine
[Install]
WantedBy=graphical-session.target
.. table::
:widths: auto
========= ============================================== ===============
package ExecStart Auto Configured
========= ============================================== ===============
ArchLinux /usr/bin/sunshine ✔
deb /usr/bin/sunshine ✔
rpm /usr/bin/sunshine ✔
AppImage ~/sunshine.AppImage ✔
Flatpak flatpak run dev.lizardbyte.app.Sunshine ✔
========= ============================================== ===============
**Start once**
.. code-block:: bash
systemctl --user start sunshine
**Start on boot**
.. code-block:: bash
systemctl --user enable sunshine
#. Reboot
.. code-block:: bash
sudo reboot now
.. tab:: macOS
.. important:: Sunshine on macOS is experimental. Gamepads do not work.
.. tab:: Homebrew
#. Install `Homebrew <https://docs.brew.sh/Installation>`__
#. Update the Homebrew sources and install Sunshine.
.. code-block:: bash
brew tap LizardByte/homebrew
brew install sunshine
.. tab:: Portfile
#. Install `MacPorts <https://www.macports.org>`__
#. Update the Macports sources.
.. code-block:: bash
sudo nano /opt/local/etc/macports/sources.conf
Add this line, replacing your username, below the line that starts with ``rsync``.
``file:///Users/<username>/ports``
``Ctrl+x``, then ``Y`` to exit and save changes.
#. Download and install by running the following code.
.. code-block:: bash
mkdir -p ~/ports/multimedia/sunshine
cd ~/ports/multimedia/sunshine
curl -OL https://github.com/LizardByte/Sunshine/releases/latest/download/Portfile
cd ~/ports
portindex
sudo port install sunshine
#. The first time you start Sunshine, you will be asked to grant access to screen recording and your microphone.
#. Optionally, install service
.. code-block:: bash
sudo port load Sunshine
Uninstall:
.. code-block:: bash
sudo port uninstall sunshine
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>`__.
.. note:: Command Keys are not forwarded by Moonlight. Right Option-Key is mapped to CMD-Key.
.. caution:: Gamepads are not currently supported.
.. tab:: Windows
.. tab:: Installer
#. Download and install ``sunshine-windows-installer.exe``
.. attention:: You should carefully select or unselect the options you want to install. Do not blindly install or
enable features.
To uninstall, find Sunshine in the list `here <ms-settings:installed-apps>`__ and select "Uninstall" from the
overflow menu. Different versions of Windows may provide slightly different steps for uninstall.
.. tab:: Standalone
.. warning:: By using this package instead of the installer, performance will be reduced. This package is not
recommended for most users. No support will be provided!
#. Download and extract ``sunshine-windows-portable.zip``
#. Open command prompt as administrator
#. Firewall rules
Install:
.. code-block:: bash
cd /d {path to extracted directory}
scripts/add-firewall-rule.bat
Uninstall:
.. code-block:: bash
cd /d {path to extracted directory}
scripts/delete-firewall-rule.bat
#. Virtual Gamepad Support
Install:
.. code-block:: bash
cd /d {path to extracted directory}
scripts/install-gamepad.bat
Uninstall:
.. code-block:: bash
cd /d {path to extracted directory}
scripts/uninstall-gamepad.bat
#. Windows service
Install:
.. code-block:: bash
cd /d {path to extracted directory}
scripts/install-service.bat
scripts/autostart-service.bat
Uninstall:
.. code-block:: bash
cd /d {path to extracted directory}
scripts/uninstall-service.bat
To uninstall, delete the extracted directory which contains the ``sunshine.exe`` file.
Usage
-----
#. If Sunshine is not installed/running as a service, then start sunshine with the following command, unless a start
command is listed in the specified package `install`_ instructions above.
.. note:: A service is a process that runs in the background. This is the default when installing Sunshine from the
Windows installer. Running multiple instances of Sunshine is not advised.
**Basic usage**
.. code-block:: bash
sunshine
**Specify config file**
.. code-block:: bash
sunshine <directory of conf file>/sunshine.conf
.. note:: You do not need to specify a config file.
If no config file is entered the default location will be used.
.. attention:: The configuration file specified will be created if it doesn't exist.
**Start Sunshine over SSH (Linux/X11)**
Assuming you are already logged into the host, you can use this command
.. code-block:: bash
ssh <user>@<ip_address> 'export DISPLAY=:0; sunshine'
If you are logged into the host with only a tty (teletypewriter), you can use ``startx`` to start the
X server prior to executing sunshine.
You nay need to add ``sleep`` between ``startx`` and ``sunshine`` to allow more time for the display to be ready.
.. code-block:: bash
ssh <user>@<ip_address> 'startx &; export DISPLAY=:0; sunshine'
.. tip:: You could also utilize the ``~/.bash_profile`` or ``~/.bashrc`` files to setup the ``DISPLAY``
variable.
.. seealso::
See :ref:`Remote SSH Headless Setup
<about/guides/linux/headless_ssh:Remote SSH Headless Setup>` on
how to setup a headless streaming server without autologin and dummy plugs (X11 + NVidia GPUs)
#. Configure Sunshine in the web ui
The web ui is available on `https://localhost:47990 <https://localhost:47990>`__ by default. You may replace
`localhost` with your internal ip address.
.. attention:: Ignore any warning given by your browser about "insecure website". This is due to the SSL certificate
being self signed.
.. caution:: If running for the first time, make sure to note the username and password that you created.
#. Add games and applications.
#. Adjust any configuration settings as needed.
#. In Moonlight, you may need to add the PC manually.
#. When Moonlight requests for you insert the pin:
- Login to the web ui
- Go to "PIN" in the Navbar
- Type in your PIN and press Enter, you should get a Success Message
- In Moonlight, select one of the Applications listed
Network
-------
The Sunshine user interface will be available on port 47990 by default.
.. warning:: Exposing ports to the internet can be dangerous. Do this at your own risk.
Arguments
---------
To get a list of available arguments run the following:
.. tab:: General
.. code-block:: bash
sunshine --help
.. tab:: AppImage
.. code-block:: bash
./sunshine.AppImage --help
.. tab:: Flatpak
.. code-block:: bash
flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --help
Shortcuts
---------
All shortcuts start with ``CTRL + ALT + SHIFT``, just like Moonlight
- ``CTRL + ALT + SHIFT + N`` - Hide/Unhide the cursor (This may be useful for Remote Desktop Mode for Moonlight)
- ``CTRL + ALT + SHIFT + F1/F12`` - Switch to different monitor for Streaming
Application List
----------------
- Applications should be configured via the web UI.
- A basic understanding of working directories and commands is required.
- You can use Environment variables in place of values
- ``$(HOME)`` will be replaced by the value of ``$HOME``
- ``$$`` will be replaced by ``$``, e.g. ``$$(HOME)`` will be become ``$(HOME)``
- ``env`` - Adds or overwrites Environment variables for the commands/applications run by Sunshine
- ``"Variable name":"Variable value"``
- ``apps`` - The list of applications
- Advanced users may want to edit the application list manually. The format is ``json``.
- Example ``json`` application:
.. code-block:: json
{
"cmd": "command to open app",
"detached": [
"some-command",
"another-command"
],
"image-path": "/full-path/to/png-image",
"name": "An App",
"output": "/full-path/to/command-log-file",
"prep-cmd": [
{
"do": "some-command",
"undo": "undo-that-command"
}
],
"working-dir": "/full-path/to/working-directory"
}
- ``cmd`` - The main application
- ``detached`` - A list of commands to be run and forgotten about
- If not specified, a process is started that sleeps indefinitely
- ``image-path`` - The full path to the cover art image to use.
- ``name`` - The name of the application/game
- ``output`` - The file where the output of the command is stored
- ``auto-detach`` - Specifies whether the app should be treated as detached if it exits quickly
- ``wait-all`` - Specifies whether to wait for all processes to terminate rather than just the initial process
- ``exit-timeout`` - Specifies how long to wait in seconds for the process to gracefully exit (default: 5 seconds)
- ``prep-cmd`` - A list of commands to be run before/after the application
- If any of the prep-commands fail, starting the application is aborted
- ``do`` - Run before the application
- If it fails, all ``undo`` commands of the previously succeeded ``do`` commands are run
- ``undo`` - Run after the application has terminated
- Failures of ``undo`` commands are ignored
- ``working-dir`` - The working directory to use. If not specified, Sunshine will use the application directory.
- For more examples see :ref:`app examples <about/guides/app_examples:app examples>`.
Considerations
--------------
- On Windows, Sunshine uses the Desktop Duplication API which only supports capturing from the GPU used for display.
If you want to capture and encode on the eGPU, connect a display or HDMI dummy display dongle to it and run the games
on that display.
- When an application is started, if there is an application already running, it will be terminated.
- When the application has been shutdown, the stream shuts down as well.
- For example, if you attempt to run ``steam`` as a ``cmd`` instead of ``detached`` the stream will immediately fail.
This is due to the method in which the steam process is executed. Other applications may behave similarly.
- This does not apply to ``detached`` applications.
- The "Desktop" app works the same as any other application except it has no commands. It does not start an application,
instead it simply starts a stream. If you removed it and would like to get it back, just add a new application with
the name "Desktop" and "desktop.png" as the image path.
- For the Linux flatpak you must prepend commands with ``flatpak-spawn --host``.
HDR Support
-----------
Streaming HDR content is officially supported on Windows hosts and experimentally supported for Linux hosts.
- General HDR support information and requirements:
- HDR must be activated in the host OS, which may require an HDR-capable display or EDID emulator dongle connected to your host PC.
- You must also enable the HDR option in your Moonlight client settings, otherwise the stream will be SDR (and probably overexposed if your host is HDR).
- A good HDR experience relies on proper HDR display calibration both in the OS and in game. HDR calibration can differ significantly between client and host displays.
- You may also need to tune the brightness slider or HDR calibration options in game to the different HDR brightness capabilities of your client's display.
- Some GPUs video encoders can produce lower image quality or encoding performance when streaming in HDR compared to SDR.
- Additional information:
.. tab:: Windows
- HDR streaming is supported for Intel, AMD, and NVIDIA GPUs that support encoding HEVC Main 10 or AV1 10-bit profiles.
- We recommend calibrating the display by streaming the Windows HDR Calibration app to your client device and saving an HDR calibration profile to use while streaming.
- Older games that use NVIDIA-specific NVAPI HDR rather than native Windows HDR support may not display properly in HDR.
.. tab:: Linux
- HDR streaming is supported for Intel and AMD GPUs that support encoding HEVC Main 10 or AV1 10-bit profiles using VAAPI.
- The KMS capture backend is required for HDR capture. Other capture methods, like NvFBC or X11, do not support HDR.
- You will need a desktop environment with a compositor that supports HDR rendering, such as Gamescope or KDE Plasma 6.
.. seealso::
`Arch wiki on HDR Support for Linux <https://wiki.archlinux.org/title/HDR_monitor_support>`__ and
`Reddit Guide for HDR Support for AMD GPUs
<https://www.reddit.com/r/linux_gaming/comments/10m2gyx/guide_alpha_test_hdr_on_linux>`__
Tutorials and Guides
--------------------
Tutorial videos are available `here <https://www.youtube.com/playlist?list=PLMYr5_xSeuXAbhxYHz86hA1eCDugoxXY0>`_.
Guides are available :doc:`here <./guides/guides>`.
.. admonition:: Community!
Tutorials and Guides are community generated. Want to contribute? Reach out to us on our discord server.

37
docs/source/about/third_party_packages.rst
View File

@ -1,37 +0,0 @@
Third Party Packages
====================
.. danger:: These packages are not maintained by LizardByte. Use at your own risk.
Chocolatey
----------
.. image:: https://img.shields.io/badge/dynamic/xml.svg?color=orange&label=chocolatey&style=for-the-badge&prefix=v&query=%2F%2Ftr%5B%40id%3D%27chocolatey%27%5D%2Ftd%5B3%5D%2Fspan%2Fa&url=https%3A%2F%2Frepology.org%2Fproject%2Fsunshine%2Fversions&logo=chocolatey
:alt: Chocolatey
:target: https://community.chocolatey.org/packages/sunshine
Flathub
-------
.. image:: https://img.shields.io/flathub/v/dev.lizardbyte.app.Sunshine?style=for-the-badge&logo=Flathub
:alt: Flathub
:target: https://flathub.org/apps/dev.lizardbyte.app.Sunshine
nixpkgs
-------
.. image:: https://img.shields.io/badge/dynamic/xml.svg?color=orange&label=nixpkgs&style=for-the-badge&prefix=v&query=%2F%2Ftr%5B%40id%3D%27nix_unstable%27%5D%2Ftd%5B3%5D%2Fspan%2Fa&url=https%3A%2F%2Frepology.org%2Fproject%2Fsunshine%2Fversions&logo=nixos
:alt: nixpgs
:target: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/servers/sunshine/default.nix
Scoop
-----
.. image:: https://img.shields.io/scoop/v/sunshine.svg?bucket=extras&style=for-the-badge&logo=data:image/vnd.microsoft.icon;base64,AAABAAEAEBAAAAEAGAAhAwAAFgAAAIlQTkcNChoKAAAADUlIRFIAAAAQAAAAEAgGAAAAH/P/YQAAAuhJREFUOE9tk1tIFFEYx7+ZXdfbrhdMElJLFCykCxL20MUW9UkkqeiOFGSWYW75EvjgVlJmlpkaJV5SMtQlMYjEROqpQoiMMEpRW2/p6q67bTuXM2dmOjPu2moNDHPm4/v/Zs7//D9KlmUNAMjkBoqiJOVJapTyqqzXXn49tCohzbRSVERPSi7tokFOSkne2rmzoED4H6C0pHwjT2G2qspsU7U+wBuzWTs8M9mlpen0YEOoMS/73DjrnMuhXFyiLEmjwZH6vmufR5DDNtHBI7b9cWNNpw9AgcVCtw6+P8R43KdkjHMM+vDqI/tywyiN5oy46KQpLEogiG0149+7rG5HGRK5o01N9VYVoPxm/ZXCOMrD95NloihiOj4qhs1K3R8IbqQFogVJAuRifrXNT3wactkGmpvrbni9UregQu7nn87X0XB3w+ZYfcruHRAVJgNtE0EclmCGM8CYC2DE5UK8TJXtzT1ZZTRSeJUHiqOvW29Vb89KKw4kYgEvgIQFGHurg3l7AlitS8CzAohYZgQB5ZU9Ovx8FcBkMkdcKEx5GL1ee1yWGcKjgWMQfHgVDVOjNPD88qHwHAYOe57GbHOcLSoqQiunYC4tT4tL0NYmbwkOx1hO1ukABITg40AkOO0BJCgiYFEAl9sBjGj/pl+nyairq5xdAdy50xbKuH+eFyUMkijdJtHQCAIGxiOQYC0nguMYmJqeVJJW29vfU7wqSErDzeuV6aQ5lUPoIjn7RI5FRIRUMQkbLC05YN42txgaEpTd89IyuNZEaGlpCZqdXsjHAj5Avp7h+c2CIIiqGGMMMzNTgDD/oLev57I3vX+T6IttRUVNvNvpusey3EGeE5QtAkI82B12YFjmXagh5ER39zOrfw7UWfDPvcl0ddP0j+lGjucylDoiZhIbvkboDccsL9q/+Hr/2YI/JDMzZ4/IIyMhRyh1XYBmKCEptqOhoWFlyHwAZZxX/YHXNK/3/tiVUfcV6T8hxMYSf1PeGAAAAABJRU5ErkJggg==
:alt: Scoop (extras bucket)
:target: https://scoop.sh/#/apps?s=0&d=1&o=true&q=sunshine
Solus
-----
.. image:: https://img.shields.io/badge/dynamic/xml.svg?color=orange&label=Solus&style=for-the-badge&prefix=v&query=%2F%2Ftr%5B%40id%3D%27solus%27%5D%2Ftd%5B3%5D%2Fspan%2Fa&url=https%3A%2F%2Frepology.org%2Fproject%2Fsunshine%2Fversions&logo=solus
:alt: Solus
:target: https://dev.getsol.us/source/sunshine

32
docs/source/building/build.rst
View File

@ -1,32 +0,0 @@
Build
=====
Sunshine binaries are built using `CMake <https://cmake.org/>`__. Cross compilation is not
supported. That means the binaries must be built on the target operating system and architecture.
Building Locally
----------------
Clone
^^^^^
Ensure `git <https://git-scm.com/>`__ is installed and run the following:
.. code-block:: bash
git clone https://github.com/lizardbyte/sunshine.git --recurse-submodules
cd sunshine && mkdir build && cd build
Compile
^^^^^^^
See the section specific to your OS.
- :ref:`Linux <building/linux:linux>`
- :ref:`macOS <building/macos:macos>`
- :ref:`Windows <building/windows:windows>`
Remote Build
------------
It may be beneficial to build remotely in some cases. This will enable easier building on different operating systems.
#. Fork the project
#. Activate workflows
#. Trigger the `CI` workflow manually
#. Download the artifacts/binaries from the workflow run summary

189
docs/source/building/linux.rst
View File

@ -1,189 +0,0 @@
Linux
=====
Requirements
------------
Debian Bookworm
^^^^^^^^^^^^^^^
Install Requirements
.. code-block:: bash
sudo apt update && sudo apt install \
build-essential \
cmake \
libayatana-appindicator3-dev \
libcap-dev \ # KMS
libcurl4-openssl-dev \
libdrm-dev \ # KMS
libevdev-dev \
libminiupnpc-dev \
libnotify-dev \
libnuma-dev \
libopus-dev \
libpulse-dev \
libssl-dev \
libva-dev \ # VA-API
libvdpau-dev \
libwayland-dev \ # Wayland
libx11-dev \ # X11
libxcb-shm0-dev \ # X11
libxcb-xfixes0-dev \ # X11
libxcb1-dev \ # X11
libxfixes-dev \ # X11
libxrandr-dev \ # X11
libxtst-dev \ # X11
nodejs \
npm \
nvidia-cuda-dev \ # Cuda, NvFBC
nvidia-cuda-toolkit # Cuda, NvFBC
Fedora 39, 40
^^^^^^^^^^^^^
Install Requirements
.. code-block:: bash
sudo dnf update && \
sudo dnf group install "Development Tools" && \
sudo dnf install \
cmake \
gcc \
gcc-c++ \
libappindicator-gtk3-devel \
libcap-devel \
libcurl-devel \
libdrm-devel \
libevdev-devel \
libnotify-devel \
libva-devel \ # VA-API
libvdpau-devel \
libX11-devel \ # X11
libxcb-devel \ # X11
libXcursor-devel \ # X11
libXfixes-devel \ # X11
libXi-devel \ # X11
libXinerama-devel \ # X11
libXrandr-devel \ # X11
libXtst-devel \ # X11
mesa-libGL-devel \
miniupnpc-devel \
npm \
numactl-devel \
openssl-devel \
opus-devel \
pulseaudio-libs-devel \
rpm-build \ # if you want to build an RPM binary package
wget \ # necessary for cuda install with `run` file
which # necessary for cuda install with `run` file
Ubuntu 22.04
^^^^^^^^^^^^
Install Requirements
.. code-block:: bash
sudo apt update && sudo apt install \
build-essential \
cmake \
libappindicator3-dev \
libcap-dev \ # KMS
libcurl4-openssl-dev \
libdrm-dev \ # KMS
libevdev-dev \
libminiupnpc-dev \
libnotify-dev \
libnuma-dev \
libopus-dev \
libpulse-dev \
libssl-dev \
libva-dev \ # VA-API
libwayland-dev \ # Wayland
libx11-dev \ # X11
libxcb-shm0-dev \ # X11
libxcb-xfixes0-dev \ # X11
libxcb1-dev \ # X11
libxfixes-dev \ # X11
libxrandr-dev \ # X11
libxtst-dev \ # X11
nodejs \
npm \
nvidia-cuda-dev \ # CUDA, NvFBC
nvidia-cuda-toolkit # CUDA, NvFBC
Ubuntu 24.04
^^^^^^^^^^^^
Install Requirements
.. code-block:: bash
sudo apt update && sudo apt install \
build-essential \
cmake \
gcc-11 \
g++-11 \
libappindicator3-dev \
libcap-dev \ # KMS
libcurl4-openssl-dev \
libdrm-dev \ # KMS
libevdev-dev \
libminiupnpc-dev \
libnotify-dev \
libnuma-dev \
libopus-dev \
libpulse-dev \
libssl-dev \
libva-dev \ # VA-API
libwayland-dev \ # Wayland
libx11-dev \ # X11
libxcb-shm0-dev \ # X11
libxcb-xfixes0-dev \ # X11
libxcb1-dev \ # X11
libxfixes-dev \ # X11
libxrandr-dev \ # X11
libxtst-dev \ # X11
nodejs \
npm \
nvidia-cuda-dev \ # CUDA, NvFBC
nvidia-cuda-toolkit # CUDA, NvFBC
Update gcc alias
.. code-block:: bash
update-alternatives --install \
/usr/bin/gcc gcc /usr/bin/gcc-11 100 \
--slave /usr/bin/g++ g++ /usr/bin/g++-11 \
--slave /usr/bin/gcov gcov /usr/bin/gcov-11 \
--slave /usr/bin/gcc-ar gcc-ar /usr/bin/gcc-ar-11 \
--slave /usr/bin/gcc-ranlib gcc-ranlib /usr/bin/gcc-ranlib-11
CUDA
----
If the version of CUDA available from your distro is not adequate, manually install CUDA.
.. tip:: The version of CUDA you use will determine compatibility with various GPU generations.
At the time of writing, the recommended version to use is CUDA ~11.8.
See `CUDA compatibility <https://docs.nvidia.com/deploy/cuda-compatibility/index.html>`__ for more info.
Select the appropriate run file based on your desired CUDA version and architecture according to
`CUDA Toolkit Archive <https://developer.nvidia.com/cuda-toolkit-archive>`__.
.. code-block:: bash
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run \
--progress=bar:force:noscroll -q --show-progress -O ./cuda.run
chmod a+x ./cuda.run
./cuda.run --silent --toolkit --toolkitpath=/usr --no-opengl-libs --no-man-page --no-drm
rm ./cuda.run
Build
-----
.. attention:: Ensure you are in the build directory created during the clone step earlier before continuing.
.. code-block:: bash
cmake ..
make -j ${nproc}
cpack -G DEB # optionally, create a deb package
cpack -G RPM # optionally, create a rpm package

53
docs/source/building/macos.rst
View File

@ -1,53 +0,0 @@
macOS
=====
Requirements
------------
macOS Big Sur and Xcode 12.5+
Use either `MacPorts <https://www.macports.org>`__ or `Homebrew <https://brew.sh>`__
MacPorts
""""""""
Install Requirements
.. code-block:: bash
sudo port install cmake curl doxygen graphviz libopus miniupnpc npm9 pkgconfig python311 py311-pip
Homebrew
""""""""
Install Requirements
.. code-block:: bash
brew install cmake doxygen graphviz icu4c miniupnpc node openssl@3 opus pkg-config python@3.11
If there are issues with an SSL header that is not found:
.. tab:: Intel
.. code-block:: bash
pushd /usr/local/include
ln -s ../opt/openssl/include/openssl .
popd
.. tab:: Apple Silicon
.. code-block:: bash
pushd /opt/homebrew/include
ln -s ../opt/openssl/include/openssl .
popd
Build
-----
.. attention:: Ensure you are in the build directory created during the clone step earlier before continuing.
.. code-block:: bash
cmake ..
make -j $(sysctl -n hw.ncpu)
cpack -G DragNDrop # optionally, create a macOS dmg package
If cmake fails complaining to find Boost, try to set the path explicitly.
``cmake -DBOOST_ROOT=[boost path] ..``, e.g., ``cmake -DBOOST_ROOT=/opt/local/libexec/boost/1.80 ..``

46
docs/source/building/windows.rst
View File

@ -1,46 +0,0 @@
Windows
=======
Requirements
------------
First you need to install `MSYS2 <https://www.msys2.org>`__, then startup "MSYS2 UCRT64" and execute the following
codes.
Update all packages:
.. code-block:: bash
pacman -Suy
Install dependencies:
.. code-block:: bash
pacman -S \
doxygen \
git \
mingw-w64-ucrt-x86_64-cmake \
mingw-w64-ucrt-x86_64-cppwinrt \
mingw-w64-ucrt-x86_64-curl \
mingw-w64-ucrt-x86_64-graphviz \
mingw-w64-ucrt-x86_64-miniupnpc \
mingw-w64-ucrt-x86_64-nlohmann-json \
mingw-w64-ucrt-x86_64-nodejs \
mingw-w64-ucrt-x86_64-nsis \
mingw-w64-ucrt-x86_64-onevpl \
mingw-w64-ucrt-x86_64-openssl \
mingw-w64-ucrt-x86_64-opus \
mingw-w64-ucrt-x86_64-rust \
mingw-w64-ucrt-x86_64-toolchain \
python \
python-pip
Build
-----
.. attention:: Ensure you are in the build directory created during the clone step earlier before continuing.
.. code-block:: bash
cmake -G "MinGW Makefiles" ..
mingw32-make -j$(nproc)
cpack -G NSIS # optionally, create a windows installer
cpack -G ZIP # optionally, create a windows standalone package

167
docs/source/conf.py
View File

@ -1,167 +0,0 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# standard imports
from datetime import datetime
import os
import shutil
import subprocess
from typing import Mapping, Optional
# re-usable functions
def _run_subprocess(
args_list: list,
cwd: Optional[str] = None,
env: Optional[Mapping] = None,
) -> bool:
og_dir = os.getcwd()
if cwd:
os.chdir(cwd)
process = subprocess.Popen(
args=args_list,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
cwd=cwd,
encoding='utf-8',
env=env,
errors='replace',
)
if cwd:
os.chdir(og_dir)
# Print stdout and stderr in real-time
# https://stackoverflow.com/a/57970619/11214013
while True:
realtime_output = process.stdout.readline()
if realtime_output == '' and process.poll() is not None:
break
if realtime_output:
print(realtime_output.strip(), flush=True)
process.stdout.close()
exit_code = process.wait()
if exit_code != 0:
print(f'::error:: Process [{args_list}] failed with exit code', exit_code)
raise RuntimeError(f'Process [{args_list}] failed with exit code {exit_code}')
else:
return True
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
script_dir = os.path.dirname(os.path.abspath(__file__)) # the directory of this file
source_dir = os.path.dirname(script_dir) # the source folder directory
root_dir = os.path.dirname(source_dir) # the root folder directory
# -- Project information -----------------------------------------------------
project = 'Sunshine'
project_copyright = f'{datetime.now ().year}, {project}'
author = 'ReenigneArcher'
# The full version, including alpha/beta/rc tags
# https://docs.readthedocs.io/en/stable/reference/environment-variables.html#envvar-READTHEDOCS_VERSION
version = os.getenv('READTHEDOCS_VERSION', 'dirty')
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'm2r2', # enable markdown files
'sphinx.ext.autosectionlabel',
'sphinx.ext.todo', # enable to-do sections
'sphinx.ext.viewcode', # add links to view source code
'sphinx_copybutton', # add a copy button to code blocks
'sphinx_inline_tabs', # add tabs
]
# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['toc.rst']
# Extensions to include.
source_suffix = ['.rst', '.md']
# -- Options for HTML output -------------------------------------------------
# images
html_favicon = os.path.join(root_dir, 'src_assets', 'common', 'assets', 'web', 'public', 'images', 'sunshine.ico')
html_logo = os.path.join(root_dir, 'sunshine.png')
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'furo'
html_theme_options = {
"top_of_page_button": "edit",
"source_edit_link": "https://github.com/lizardbyte/sunshine/tree/master/docs/source/{filename}",
}
# extension config options
autosectionlabel_prefix_document = True # Make sure the target is unique
todo_include_todos = True
# disable epub mimetype warnings
# https://github.com/readthedocs/readthedocs.org/blob/eadf6ac6dc6abc760a91e1cb147cc3c5f37d1ea8/docs/conf.py#L235-L236
suppress_warnings = ["epub.unknown_project_files"]
doxygen_cmd = os.getenv('DOXY_PATH', 'doxygen')
print(f'doxygen command: {doxygen_cmd}')
# get doxygen version
doxy_version = _run_subprocess(
args_list=[doxygen_cmd, '--version'],
cwd=source_dir,
)
# create build directories, as doxygen fails to create it in macports and docker
directories = [
os.path.join(source_dir, 'build'),
os.path.join(source_dir, 'build', 'doxygen', 'doxyhtml'),
]
for d in directories:
os.makedirs(
name=d,
exist_ok=True,
)
# remove existing html files
# doxygen builds will not re-generated if the html directory already exists
html_dir = os.path.join(source_dir, 'build', 'html')
if os.path.exists(html_dir):
shutil.rmtree(html_dir)
# run doxygen
doxy_proc = _run_subprocess(
args_list=[doxygen_cmd, 'Doxyfile'],
cwd=source_dir
)
# copy doxygen html files
html_extra_path = [
os.path.join(source_dir, 'build', 'doxygen'), # the final directory is omitted in order to have a proper path
]

25
docs/source/contributing/contributing.rst
View File

@ -1,25 +0,0 @@
Contributing
============
Read our contribution guide in our organization level
`docs <https://lizardbyte.readthedocs.io/en/latest/developers/contributing.html>`__.
Web UI
------
The Web UI uses `Vite <https://vitejs.dev/>`__ as its build system, to handle the integration of the NPM libraries.
The HTML pages used by the Web UI are found in ``src_assets/common/assets/web``.
`EJS <https://www.npmjs.com/package/vite-plugin-ejs>`__ is used as a templating system for the pages (check ``template_header.html`` and ``template_header_main.html``).
The Style System is provided by `Bootstrap <https://getbootstrap.com/>`__.
The JS framework used by the more interactive pages is `Vue <https://vuejs.org/>`__.
Building
^^^^^^^^
Sunshine already builds the UI as part of its build process, but you can make faster changes by starting vite manually.
.. code-block:: bash
npm run dev

113
docs/source/contributing/localization.rst
View File

@ -1,113 +0,0 @@
Localization
============
Sunshine and related LizardByte projects are being localized into various languages. The default language is
`en` (English).
.. image:: https://app.lizardbyte.dev/uno/crowdin/LizardByte_graph.svg
CrowdIn
-------
The translations occur on `CrowdIn <https://translate.lizardbyte.dev/>`__. Anyone is free to contribute to
localization there.
**Translations Basics**
- The brand names `LizardByte` and `Sunshine` should never be translated.
- Other brand names should never be translated.
Examples:
- AMD
- Nvidia
**CrowdIn Integration**
How does it work?
When a change is made to sunshine source code, a workflow generates new translation templates
that get pushed to CrowdIn automatically.
When translations are updated on CrowdIn, a push gets made to the `l10n_master` branch and a PR is made against the
`master` branch. Once PR is merged, all updated translations are part of the project and will be included in the
next release.
Extraction
----------
.. tab:: UI
Sunshine uses `Vue I18n <https://vue-i18n.intlify.dev/>`__ for localizing the UI.
The following is a simple example of how to use it.
- Add the string to `src_assets/common/assets/web/public/assets/locale/en.json`, in English.
.. code-block:: json
{
"index": {
"welcome": "Hello, Sunshine!"
}
}
.. note:: The json keys should be sorted alphabetically. You can use `jsonabc <https://novicelab.org/jsonabc/>`__
to sort the keys.
.. attention:: Due to the integration with Crowdin, it is important to only add strings to the `en.json` file,
and to not modify any other language files. After the PR is merged, the translations can take place
on `CrowdIn <https://translate.lizardbyte.dev/>`__. Once the translations are complete, a PR will be made
to merge the translations into Sunshine.
- Use the string in a Vue component.
.. code-block:: html
<template>
<div>
<p>{{ $t('index.welcome') }}</p>
</div>
</template>
.. tip:: More formatting examples can be found in the
`Vue I18n guide <https://kazupon.github.io/vue-i18n/guide/formatting.html>`__.
.. tab:: C++
There should be minimal cases where strings need to be extracted from C++ source code; however it may be necessary in
some situations. For example the system tray icon could be localized as it is user interfacing.
- Wrap the string to be extracted in a function as shown.
.. code-block:: cpp
#include <boost/locale.hpp>
#include <string>
std::string msg = boost::locale::translate("Hello world!");
.. tip:: More examples can be found in the documentation for
`boost locale <https://www.boost.org/doc/libs/1_70_0/libs/locale/doc/html/messages_formatting.html>`__.
.. warning:: This is for information only. Contributors should never include manually updated template files, or
manually compiled language files in Pull Requests.
Strings are automatically extracted from the code to the `locale/sunshine.po` template file. The generated file is
used by CrowdIn to generate language specific template files. The file is generated using the
`.github/workflows/localize.yml` workflow and is run on any push event into the `master` branch. Jobs are only run if
any of the following paths are modified.
.. code-block:: yaml
- 'src/**'
When testing locally it may be desirable to manually extract, initialize, update, and compile strings. Python is
required for this, along with the python dependencies in the `./scripts/requirements.txt` file. Additionally,
`xgettext <https://www.gnu.org/software/gettext/>`__ must be installed.
**Extract, initialize, and update**
.. code-block:: bash
python ./scripts/_locale.py --extract --init --update
**Compile**
.. code-block:: bash
python ./scripts/_locale.py --compile
.. attention:: Due to the integration with Crowdin, it is important to not include any extracted or compiled files in
Pull Requests. The files are automatically generated and updated by the workflow. Once the PR is merged, the
translations can take place on `CrowdIn <https://translate.lizardbyte.dev/>`__. Once the translations are
complete, a PR will be made to merge the translations into Sunshine.

143
docs/source/contributing/testing.rst
View File

@ -1,143 +0,0 @@
Testing
=======
Clang Format
------------
Source code is tested against the `.clang-format` file for linting errors. The workflow file responsible for clang
format testing is `.github/workflows/cpp-clang-format-lint.yml`.
Test clang-format locally.
.. code-block:: bash
find ./ -iname *.cpp -o -iname *.h -iname *.m -iname *.mm | xargs clang-format -i
Sphinx
------
.. note:: Documentation is now a cmake target and this is all handled by the cmake build system. When compiling docs
as a target, simply install Python, Doxygen, and Graphviz. The installation of python dependencies will be handled
automatically inside a virtual environment. The following instructions are for manual building of the docs.
Sunshine uses `Sphinx <https://www.sphinx-doc.org/en/master/>`__ for documentation building. Sphinx, along with other
required python dependencies are included in the `./docs/requirements.txt` file. Python is required to build
sphinx docs. Installation and setup of python will not be covered here.
Doxygen is used to generate the XML files required by Sphinx. Doxygen can be obtained from
`Doxygen downloads <https://www.doxygen.nl/download.html>`__. Ensure that the `doxygen` executable is in your path.
.. seealso::
Sphinx is configured to use the graphviz extension. To obtain the dot executable from the Graphviz library,
see the `library’s downloads section <https://graphviz.org/download/>`__.
The config file for Sphinx is `docs/source/conf.py`. This is already included in the repo and should not be modified.
The config file for Doxygen is `docs/Doxyfile`. This is already included in the repo and should not be modified.
Test with Sphinx
.. code-block:: bash
cd docs
make html
Alternatively
.. code-block:: bash
cd docs
sphinx-build -b html source build
Lint with rstcheck
.. code-block:: bash
rstcheck -r .
Check formatting with rstfmt
.. code-block:: bash
rstfmt --check --diff -w 120 .
Format inplace with rstfmt
.. code-block:: bash
rstfmt -w 120 .
Unit Testing
------------
Sunshine uses `Google Test <https://github.com/google/googletest>`__ for unit testing. Google Test is included in the
repo as a submodule. The test sources are located in the `./tests` directory.
The tests need to be compiled into an executable, and then run. The tests are built using the normal build process, but
can be disabled by setting the `BUILD_TESTS` CMake option to `OFF`.
To run the tests, execute the following command from the build directory:
.. tab:: Linux
.. code-block:: bash
pushd tests
./test_sunshine
popd
.. tab:: macOS
.. code-block:: bash
pushd tests
./test_sunshine
popd
.. tab:: Windows
.. code-block:: bash
pushd tests
test_sunshine.exe
popd
To see all available options, run the tests with the `--help` option.
.. tab:: Linux
.. code-block:: bash
pushd tests
./test_sunshine --help
popd
.. tab:: macOS
.. code-block:: bash
pushd tests
./test_sunshine --help
popd
.. tab:: Windows
.. code-block:: bash
pushd tests
test_sunshine.exe --help
popd
Some tests rely on Python to run. CMake will search for Python and enable the docs tests if it is found, otherwise
cmake will fail. You can manually disable the tests by setting the `TESTS_ENABLE_PYTHON_TESTS` CMake option to
`OFF`.
.. tip::
See the googletest `FAQ <https://google.github.io/googletest/faq.html>`__ for more information on how to use
Google Test.
We use `gcovr <https://www.gcovr.com/>`__ to generate code coverage reports,
and `Codecov <https://about.codecov.io/>`__ to analyze the reports for all PRs and commits.
Codecov will fail a PR if the total coverage is reduced too much, or if not enough of the diff is covered by tests.
In some cases, the code cannot be covered when running the tests inside of GitHub runners. For example, any test that
needs access to the GPU will not be able to run. In these cases, the coverage can be omitted by adding comments to the
code. See the `gcovr documentation <https://gcovr.com/en/stable/guide/exclusion-markers.html#exclusion-markers>`__ for
more information.
Even if your changes cannot be covered in the CI, we still encourage you to write the tests for them. This will allow
maintainers to run the tests locally.

28
docs/source/gamestream/gamestream.rst
View File

@ -1,28 +0,0 @@
GameStream
==========
Nvidia announced that their GameStream service for Nvidia Games clients will be discontinued in February 2023.
Luckily, Sunshine performance is now on par with Nvidia GameStream. Many users have even reported that Sunshine
outperforms GameStream, so rest assured that Sunshine will be equally performant moving forward.
Migration
---------
We have developed a simple migration tool to help you migrate your GameStream games and apps to Sunshine automatically.
Please check out our `GSMS <https://github.com/LizardByte/GSMS>`__ project if you're interested in an automated
migration option. GSMS offers the ability to migrate your custom and auto-detected games and apps. The
working directory, command, and image are all set in Sunshine's ``apps.json`` file. The box-art image is also copied
to a specified directory.
Internet Streaming
------------------
If you are using the Moonlight Internet Hosting Tool, you can remove it from your system when you migrate to Sunshine.
To stream over the Internet with Sunshine and a UPnP-capable router, enable the UPnP option in the Sunshine Web UI.
.. note:: Running Sunshine together with versions of the Moonlight Internet Hosting Tool prior to v5.6 will cause UPnP
port forwarding to become unreliable. Either uninstall the tool entirely or update it to v5.6 or later.
Limitations
-----------
Sunshine does have some limitations, as compared to Nvidia GameStream.
- Automatic game/application list.
- Changing game settings automatically, to optimize streaming.

17
docs/source/history/changelog.rst
View File

@ -1,17 +0,0 @@
Changelog
=========
.. only:: epub
You can view the changelog in the
`online version <https://github.com/LizardByte/Sunshine/changelog/CHANGELOG.md>`__.
.. only:: html
.. raw:: html
<script type="module" src="https://md-block.verou.me/md-block.js"></script>
<md-block
hmin="2"
src="https://raw.githubusercontent.com/LizardByte/Sunshine/changelog/CHANGELOG.md">
</md-block>

3
docs/source/index.rst
View File

@ -1,3 +0,0 @@
Table of Contents
=================
.. include:: toc.rst

114
docs/source/source_code/source_code.rst
View File

@ -1,114 +0,0 @@
Source Code
===========
We are in process of improving the source code documentation. Code should be documented using Doxygen syntax.
Many examples exist throughout the codebase.
Source
------
For generated docs, refer to the `Doxygen Documentation <../doxyhtml/index.html>`_.
Guidelines
----------
Doxygen Comments
^^^^^^^^^^^^^^^^
- Use Doxygen comments to document all files, functions, classes, and variables.
- `Inline documentation block <Inline Documentation Blocks>`_ should use the following format:
.. code-block:: cpp
///< A brief description of the member.
- Multi-line comments, such as for a `documentation block <Documentation Blocks>`_, should use the following format:
.. code-block:: cpp
/**
* @brief A brief description of the member.
* More detailed description of the member.
*/
Documentation Blocks
^^^^^^^^^^^^^^^^^^^^
Documentation blocks should be placed above the declaration of the function, class, or variable. Below is an example
of a documentation block for the main function.
.. code-block:: cpp
/**
* @brief Main application entry point.
* @param argc The number of arguments.
* @param argv The arguments.
* @return The exit code.
* @examples
* main(1, const char* args[] = {"hello", "markdown", nullptr});
* @examples_end
*/
int main(int argc, char *argv[]);
.. attention:: The `@examples` and `@examples_end` tags are not standard Doxygen tags. They are custom aliases
we have specified to simplify documenting examples. Do not confuse this with the standard `@example` tag.
In some cases, it could be valuable to have slightly different documentation for the definitions, especially when
the definition may change depending on the platform or other factors. In such cases, you should put the documentation
that is common in the declaration and the definition-specific documentation in the definition. Below is an example of
how to document the declaration and definition of a function.
.. code-block:: cpp
// myFile.h
/**
* @brief A brief description of the function.
* @param arg1 Describe the first argument.
* @param arg2 Describe the second argument.
* @return Describe the result.
*/
int myFunction(int arg1, int arg2);
// myFile.cpp
/**
* This describes anything which is specific to the implementation of the function.
*/
int myFunction(int arg1, int arg2)
{
// Implementation
}
File Documentation
^^^^^^^^^^^^^^^^^^
The file documentation block must be placed at the top of the file. If it is not present, Doxygen will ignore the file.
Understandably, it is difficult to make a creative description for every file although it is still required.
Below is an example of a file documentation block.
.. code-block:: cpp
/**
* @file src/main.cpp
* @brief Main application entry point.
*/
Inline Documentation Blocks
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Inline comments can be used to describe enum values, variables, and other code constructs.
To document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation
block after the member instead of before. For this purpose you have to put an additional `<` marker in the comment
block. Below is an example of an inline comment for an enum value.
.. code-block:: cpp
enum class MyEnum
{
FIRST_VALUE, ///< A brief description of the FIRST_VALUE
SECOND_VALUE ///< A brief description of the SECOND_VALUE
};
Custom Aliases
^^^^^^^^^^^^^^
We have defined some custom aliases to simplify documenting examples.
- ``@examples`` - Start of an example block. This will format the following text as ``cpp``.
- ``@examples_end`` - End of an example block.
- ``@rst`` - Start of a reStructuredText block. This will format the following text as reStructuredText.
- ``@rst_end`` - End of a reStructuredText block.

60
docs/source/toc.rst
View File

@ -1,60 +0,0 @@
.. toctree::
:maxdepth: 2
:caption: About
about/overview
about/setup
about/docker
about/third_party_packages
about/guides/guides
about/advanced_usage
.. toctree::
:maxdepth: 2
:caption: GameStream
gamestream/gamestream
.. toctree::
:maxdepth: 2
:caption: Troubleshooting
troubleshooting/general
troubleshooting/linux
troubleshooting/macos
troubleshooting/windows
.. toctree::
:maxdepth: 2
:caption: Build
building/build
building/linux
building/macos
building/windows
.. toctree::
:maxdepth: 2
:caption: Contributing
contributing/contributing
contributing/localization
contributing/testing
.. toctree::
:maxdepth: 2
:caption: Legal
legal/legal
.. toctree::
:maxdepth: 2
:caption: source
source_code/source_code
.. toctree::
:maxdepth: 2
:caption: History
history/changelog

97
docs/source/troubleshooting/general.rst
View File

@ -1,97 +0,0 @@
General
=======
Forgotten Credentials
---------------------
If you forgot your credentials to the web UI, try this.
.. tab:: General
.. code-block:: bash
sunshine --creds {new-username} {new-password}
.. tab:: AppImage
.. code-block:: bash
./sunshine.AppImage --creds {new-username} {new-password}
.. tab:: Flatpak
.. code-block:: bash
flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --creds {new-username} {new-password}
Web UI Access
-------------
Can't access the web UI?
#. Check firewall rules.
Controller works on Steam but not in games
------------------------------------------
One trick might be to change Steam settings and check or uncheck the configuration to support Xbox/Playstation
controllers and leave only support for Generic controllers.
Also, if you have many controllers already directly connected to the host, it might help to disable them so that the
Sunshine provided controller (connected to the guest) is the "first" one. In Linux this can be accomplished on USB
devices by finding the device in `/sys/bus/usb/devices/` and writing `0` to the `authorized` file.
Network performance test
------------------------
For real-time game streaming the most important characteristic of the network
path between server and client is not pure bandwidth but rather stability and
consistency (low latency with low variance, minimal or no packet loss).
The network can be tested using the multi-platform tool `iPerf3 <https://iperf.fr>`__.
On the Sunshine host ``iperf3`` is started in server mode:
.. code-block:: bash
iperf3 -s
On the client device iperf3 is asked to perform a 60-second UDP test in reverse
direction (from server to client) at a given bitrate (e.g. 50 Mbps):
.. code-block:: bash
iperf3 -c {HostIpAddress} -t 60 -u -R -b 50M
Watch the output on the client for packet loss and jitter values. Both should be
(very) low. Ideally packet loss remains less than 5% and jitter below 1ms.
For Android clients use `PingMaster <https://play.google.com/store/apps/details?id=com.appplanex.pingmasternetworktools>`__.
For iOS clients use `HE.NET Network Tools <https://apps.apple.com/us/app/he-net-network-tools/id858241710>`__.
If you are testing a remote connection (over the internet) you will need to
forward the port 5201 (TCP and UDP) from your host.
Packet loss (Buffer overrun)
----------------------------
If the host PC (running Sunshine) has a much faster connection to the network
than the slowest segment of the network path to the client device (running
Moonlight), massive packet loss can occur: Sunshine emits its stream in bursts
every 16ms (for 60fps) but those bursts can't be passed on fast enough to the
client and must be buffered by one of the network devices inbetween. If the
bitrate is high enough, these buffers will overflow and data will be discarded.
This can easily happen if e.g. the host has a 2.5 Gbit/s connection and the
client only 1 Gbit/s or Wifi. Similarly a 1 Gbps host may be too fast for a
client having only a 100 Mbps interface.
As a workaround the transmission speed of the host NIC can be reduced: 1 Gbps
instead of 2.5 or 100 Mbps instead of 1 Gbps. (A technically more advanced
solution would be to configure traffic shaping rules at the OS-level, so that
only Sunshine's traffic is slowed down.)
Sunshine versions > 0.23.1 include improved networking code that should
alleviate or even solve this issue (without reducing the NIC speed).
Packet loss (MTU)
-----------------
Albeit unlikely, some guests might work better with a lower `MTU
<https://en.wikipedia.org/wiki/Maximum_transmission_unit>`__ from the host. For example, a LG TV was found to have 30-60%
packet loss when the host had MTU set to 1500 and 1472, but 0% packet loss with a MTU of 1428 set in the network card
serving the stream (a Linux PC). It's unclear how that helped precisely so it's a last resort suggestion.

76
docs/source/troubleshooting/linux.rst
View File

@ -1,76 +0,0 @@
Linux
=====
Hardware Encoding fails
-----------------------
Due to legal concerns, Mesa has disabled hardware decoding and encoding by default.
.. code-block:: text
Error: Could not open codec [h264_vaapi]: Function not implemented
If you see the above error in the Sunshine logs, compiling `Mesa`
manually, may be required. See the official Mesa3D `Compiling and Installing <https://docs.mesa3d.org/install.html>`__
documentation for instructions.
.. important:: You must re-enable the disabled encoders. You can do so, by passing the following argument to the build
system. You may also want to enable decoders, however that is not required for Sunshine and is not covered here.
.. code-block:: bash
-Dvideo-codecs=h264enc,h265enc
.. note:: Other build options are listed in the
`meson options <https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/meson_options.txt>`__ file.
KMS Streaming fails
-------------------
If screencasting fails with KMS, you may need to run the following to force unprivileged screencasting.
.. code-block:: bash
sudo setcap -r $(readlink -f $(which sunshine))
.. note:: The above command will not work with the AppImage or Flatpak packages.
Please refer to the :ref:`Setup guide <about/setup:Install>` for more
specific instructions.
KMS streaming fails on Nvidia GPUs
----------------------------------
If KMS screen capture results in a black screen being streamed, you may need to
set the parameter ``modeset=1`` for Nvidia's kernel module. This can be done by
adding the following directive to the kernel command line:
.. code-block::
nvidia_drm.modeset=1
Consult your distribution's documentation for details on how to do this. (Most
often grub is used to load the kernel and set its command line.)
AMD encoding latency issues
---------------------------
If you notice unexpectedly high encoding latencies (e.g. in Moonlight's
performance overlay) or strong fluctuations thereof, this is due to
`missing support <https://gitlab.freedesktop.org/drm/amd/-/issues/3336>`_
in Mesa/libva for AMD's low latency encoder mode. This is particularly
problematic at higher resolutions (4K).
Only the most recent development versions of mesa include support for this
low-latency mode. It will be included in Mesa-24.2.
In order to enable it, Sunshine has to be started with a special environment
variable:
.. code-block:: bash
AMD_DEBUG=lowlatencyenc sunshine
To check whether low-latency mode is being used, one can watch the ``VCLK`` and
``DCLK`` frequencies in ``amdgpu_top``. Without this encoder tuning both clock
frequencies will fluctuate strongly, whereas with active low-latency encoding
they will stay high as long as the encoder is used.
Gamescope compatibility
-----------------------
Some users have reported stuttering issues when streaming games running within Gamescope.

13
docs/source/troubleshooting/macos.rst
View File

@ -1,13 +0,0 @@
macOS
=====
Dynamic session lookup failed
-----------------------------
If you get this error:
`Dynamic session lookup supported but failed: launchd did not provide a socket path, verify that
org.freedesktop.dbus-session.plist is loaded!`
Try this.
.. code-block:: bash
launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plist

14
docs/source/troubleshooting/windows.rst
View File

@ -1,14 +0,0 @@
Windows
=======
No gamepad detected
-------------------
#. Verify that you've installed `Nefarius Virtual Gamepad <https://github.com/nefarius/ViGEmBus/releases/latest>`__.
Permission denied
-----------------
Since Sunshine runs as a service on Windows, it may not have the same level of access that your regular user account
has. You may get permission denied errors when attempting to launch a game or application from a non system drive.
You will need to modify the security permissions on your disk. Ensure that user/principal SYSTEM has full
permissions on the disk.

26
docs/third_party_packages.md Normal file
View File

@ -0,0 +1,26 @@
# Third-Party Packages
@danger{These packages are not maintained by LizardByte. Use at your own risk.}
## Chocolatey
[![Chocolatey](https://img.shields.io/badge/dynamic/xml.svg?color=orange&label=chocolatey&style=for-the-badge&prefix=v&query=%2F%2Ftr%5B%40id%3D%27chocolatey%27%5D%2Ftd%5B3%5D%2Fspan%2Fa&url=https%3A%2F%2Frepology.org%2Fproject%2Fsunshine%2Fversions&logo=chocolatey)](https://community.chocolatey.org/packages/sunshine)
## Flathub
[![Flathub](https://img.shields.io/flathub/v/dev.lizardbyte.app.Sunshine?style=for-the-badge&logo=Flathub)](https://flathub.org/apps/dev.lizardbyte.app.Sunshine)
## nixpkgs
[![nixpkgs](https://img.shields.io/badge/dynamic/xml.svg?color=orange&label=nixpkgs&style=for-the-badge&prefix=v&query=%2F%2Ftr%5B%40id%3D%27nix_unstable%27%5D%2Ftd%5B3%5D%2Fspan%2Fa&url=https%3A%2F%2Frepology.org%2Fproject%2Fsunshine%2Fversions&logo=nixos)](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/servers/sunshine/default.nix)
## Scoop
[![Scoop (extras bucket)](https://img.shields.io/scoop/v/sunshine.svg?bucket=extras&style=for-the-badge&logo=data:image/vnd.microsoft.icon;base64,AAABAAEAEBAAAAEAGAAhAwAAFgAAAIlQTkcNChoKAAAADUlIRFIAAAAQAAAAEAgGAAAAH/P/YQAAAuhJREFUOE9tk1tIFFEYx7+ZXdfbrhdMElJLFCykCxL20MUW9UkkqeiOFGSWYW75EvjgVlJmlpkaJV5SMtQlMYjEROqpQoiMMEpRW2/p6q67bTuXM2dmOjPu2moNDHPm4/v/Zs7//D9KlmUNAMjkBoqiJOVJapTyqqzXXn49tCohzbRSVERPSi7tokFOSkne2rmzoED4H6C0pHwjT2G2qspsU7U+wBuzWTs8M9mlpen0YEOoMS/73DjrnMuhXFyiLEmjwZH6vmufR5DDNtHBI7b9cWNNpw9AgcVCtw6+P8R43KdkjHMM+vDqI/tywyiN5oy46KQpLEogiG0149+7rG5HGRK5o01N9VYVoPxm/ZXCOMrD95NloihiOj4qhs1K3R8IbqQFogVJAuRifrXNT3wactkGmpvrbni9UregQu7nn87X0XB3w+ZYfcruHRAVJgNtE0EclmCGM8CYC2DE5UK8TJXtzT1ZZTRSeJUHiqOvW29Vb89KKw4kYgEvgIQFGHurg3l7AlitS8CzAohYZgQB5ZU9Ovx8FcBkMkdcKEx5GL1ee1yWGcKjgWMQfHgVDVOjNPD88qHwHAYOe57GbHOcLSoqQiunYC4tT4tL0NYmbwkOx1hO1ukABITg40AkOO0BJCgiYFEAl9sBjGj/pl+nyairq5xdAdy50xbKuH+eFyUMkijdJtHQCAIGxiOQYC0nguMYmJqeVJJW29vfU7wqSErDzeuV6aQ5lUPoIjn7RI5FRIRUMQkbLC05YN42txgaEpTd89IyuNZEaGlpCZqdXsjHAj5Avp7h+c2CIIiqGGMMMzNTgDD/oLev57I3vX+T6IttRUVNvNvpusey3EGeE5QtAkI82B12YFjmXagh5ER39zOrfw7UWfDPvcl0ddP0j+lGjucylDoiZhIbvkboDccsL9q/+Hr/2YI/JDMzZ4/IIyMhRyh1XYBmKCEptqOhoWFlyHwAZZxX/YHXNK/3/tiVUfcV6T8hxMYSf1PeGAAAAABJRU5ErkJggg==)](https://scoop.sh/#/apps?s=0&d=1&o=true&q=sunshine)
## Solus
[![Solus](https://img.shields.io/badge/dynamic/xml.svg?color=orange&label=Solus&style=for-the-badge&prefix=v&query=%2F%2Ftr%5B%40id%3D%27solus%27%5D%2Ftd%5B3%5D%2Fspan%2Fa&url=https%3A%2F%2Frepology.org%2Fproject%2Fsunshine%2Fversions&logo=solus)](https://dev.getsol.us/source/sunshine)
<div class="section_buttons">
| Previous | Next |
|:------------------------------|------------------------------------------------:|
| [Docker](../DOCKER_README.md) | [Gamestream Migration](gamestream_migration.md) |
</div>

200
docs/troubleshooting.md Normal file
View File

@ -0,0 +1,200 @@
# Troubleshooting
## General
### Forgotten Credentials
If you forgot your credentials to the web UI, try this.
@tabs{
@tab{General | ```bash
sunshine --creds {new-username} {new-password}
```
}
@tab{AppImage | ```bash
./sunshine.AppImage --creds {new-username} {new-password}
```
}
@tab{Flatpak | ```bash
flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --creds {new-username} {new-password}
```
}
}
@tip{Don't forget to replace `{new-username}` and `{new-password}` with your new credentials.
Do not include the curly braces.}
### Web UI Access
Can't access the web UI?
1. Check firewall rules.
### Controller works on Steam but not in games
One trick might be to change Steam settings and check or uncheck the configuration to support Xbox/Playstation
controllers and leave only support for Generic controllers.
Also, if you have many controllers already directly connected to the host, it might help to disable them so that the
Sunshine provided controller (connected to the guest) is the "first" one. In Linux this can be accomplished on USB
devices by finding the device in `/sys/bus/usb/devices/` and writing `0` to the `authorized` file.
### Network performance test
For real-time game streaming the most important characteristic of the network
path between server and client is not pure bandwidth but rather stability and
consistency (low latency with low variance, minimal or no packet loss).
The network can be tested using the multi-platform tool [iPerf3](https://iperf.fr).
On the Sunshine host `iperf3` is started in server mode:
```bash
iperf3 -s
```
On the client device iperf3 is asked to perform a 60-second UDP test in reverse
direction (from server to client) at a given bitrate (e.g. 50 Mbps):
```bash
iperf3 -c {HostIpAddress} -t 60 -u -R -b 50M
```
Watch the output on the client for packet loss and jitter values. Both should be
(very) low. Ideally packet loss remains less than 5% and jitter below 1ms.
For Android clients use
[PingMaster](https://play.google.com/store/apps/details?id=com.appplanex.pingmasternetworktools).
For iOS clients use [HE.NET Network Tools](https://apps.apple.com/us/app/he-net-network-tools/id858241710).
If you are testing a remote connection (over the internet) you will need to
forward the port 5201 (TCP and UDP) from your host.
### Packet loss (Buffer overrun)
If the host PC (running Sunshine) has a much faster connection to the network
than the slowest segment of the network path to the client device (running
Moonlight), massive packet loss can occur: Sunshine emits its stream in bursts
every 16ms (for 60fps) but those bursts can't be passed on fast enough to the
client and must be buffered by one of the network devices inbetween. If the
bitrate is high enough, these buffers will overflow and data will be discarded.
This can easily happen if e.g. the host has a 2.5 Gbit/s connection and the
client only 1 Gbit/s or Wi-Fi. Similarly, a 1 Gbps host may be too fast for a
client having only a 100 Mbps interface.
As a workaround the transmission speed of the host NIC can be reduced: 1 Gbps
instead of 2.5 or 100 Mbps instead of 1 Gbps. (A technically more advanced
solution would be to configure traffic shaping rules at the OS-level, so that
only Sunshine's traffic is slowed down.)
Sunshine versions > 0.23.1 include improved networking code that should
alleviate or even solve this issue (without reducing the NIC speed).
### Packet loss (MTU)
Although unlikely, some guests might work better with a lower
[MTU](https://en.wikipedia.org/wiki/Maximum_transmission_unit) from the host.
For example, a LG TV was found to have 30-60% packet loss when the host had MTU
set to 1500 and 1472, but 0% packet loss with a MTU of 1428 set in the network card
serving the stream (a Linux PC). It's unclear how that helped precisely, so it's a last
resort suggestion.
## Linux
### Hardware Encoding fails
Due to legal concerns, Mesa has disabled hardware decoding and encoding by default.
```txt
Error: Could not open codec [h264_vaapi]: Function not implemented
```
If you see the above error in the Sunshine logs, compiling *Mesa* manually, may be required. See the official Mesa3D
[Compiling and Installing](https://docs.mesa3d.org/install.html) documentation for instructions.
@important{You must re-enable the disabled encoders. You can do so, by passing the following argument to the build
system. You may also want to enable decoders, however that is not required for Sunshine and is not covered here.
```bash
-Dvideo-codecs=h264enc,h265enc
```
}
@note{Other build options are listed in the
[meson options](https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/meson_options.txt) file.}
### KMS Streaming fails
If screencasting fails with KMS, you may need to run the following to force unprivileged screencasting.
```bash
sudo setcap -r $(readlink -f $(which sunshine))
```
@note{The above command will not work with the AppImage or Flatpak packages. Please refer to the
[AppImage setup](md_docs_2getting__started.html#appimage) or
[Flatpak setup](md_docs_2getting__started.html#flatpak) for more specific instructions.}
### KMS streaming fails on Nvidia GPUs
If KMS screen capture results in a black screen being streamed, you may need to
set the parameter `modeset=1` for Nvidia's kernel module. This can be done by
adding the following directive to the kernel command line:
```bash
nvidia_drm.modeset=1
```
Consult your distribution's documentation for details on how to do this. (Most
often grub is used to load the kernel and set its command line.)
### AMD encoding latency issues
If you notice unexpectedly high encoding latencies (e.g. in Moonlight's
performance overlay) or strong fluctuations thereof, this is due to
[missing support](https://gitlab.freedesktop.org/drm/amd/-/issues/3336)
in Mesa/libva for AMD's low latency encoder mode. This is particularly
problematic at higher resolutions (4K).
Only the most recent development versions of mesa include support for this
low-latency mode. It will be included in Mesa-24.2.
In order to enable it, Sunshine has to be started with a special environment
variable:
```bash
AMD_DEBUG=lowlatencyenc sunshine
```
To check whether low-latency mode is being used, one can watch the `VCLK` and
`DCLK` frequencies in `amdgpu_top`. Without this encoder tuning both clock
frequencies will fluctuate strongly, whereas with active low-latency encoding
they will stay high as long as the encoder is used.
### Gamescope compatibility
Some users have reported stuttering issues when streaming games running within Gamescope.
## macOS
### Dynamic session lookup failed
If you get this error:
> Dynamic session lookup supported but failed: launchd did not provide a socket path, verify that
> org.freedesktop.dbus-session.plist is loaded!
Try this.
```bash
launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plist
```
## Windows
### No gamepad detected
Verify that you've installed [Nefarius Virtual Gamepad](https://github.com/nefarius/ViGEmBus/releases/latest).
### Permission denied
Since Sunshine runs as a service on Windows, it may not have the same level of access that your regular user account
has. You may get permission denied errors when attempting to launch a game or application from a non system drive.
You will need to modify the security permissions on your disk. Ensure that user/principal SYSTEM has full
permissions on the disk.
<div class="section_buttons">
| Previous | Next |
|:--------------------------------------------|------------------------:|
| [Performance Tuning](performance_tuning.md) | [Building](building.md) |
</div>

1
packaging/linux/Arch/PKGBUILD
View File

@ -46,7 +46,6 @@ makedepends=(
'make'
'nodejs'
'npm'
'python'
)
optdepends=(

4
packaging/macos/Portfile
View File

@ -34,9 +34,7 @@ post-fetch {
depends_build-append port:doxygen \
port:graphviz \
port:npm9 \
port:pkgconfig \
port:python311 \
port:py311-pip
port:pkgconfig
depends_lib port:curl \
port:libopus \

1
packaging/sunshine.rb
View File

@ -148,7 +148,6 @@ class @PROJECT_NAME@ < Formula
system bin/"sunshine", "--version"
# run the test suite
# cannot build tests with python tests because homebrew destroys the source directory
system bin/"test_sunshine", "--gtest_color=yes"
end
end

1
third-party/doxyconfig vendored Submodule

@ -0,0 +1 @@
Subproject commit 671b494f3cbe8597a36d81869a864dc9fff497f4

1
third-party/doxygen-awesome-css vendored

@ -1 +0,0 @@
Subproject commit 28ed396de19cd3d803bcb483dceefdb6d03b1b2b