diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 60c91f8d..da3cc6ed 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -150,7 +150,7 @@ jobs: strategy: fail-fast: true # false to test all, true to fail entire job if any fail matrix: - distro: [ debian, ubuntu_18_04, ubuntu_20_04, ubuntu_21_04, ubuntu_21_10 ] + distro: [ debian, ubuntu_18_04, ubuntu_20_04, ubuntu_21_10 ] package: [ -p ] extension: [ deb ] include: # package these differently diff --git a/.github/workflows/clang.yml b/.github/workflows/clang.yml index 2ab2f600..f096c5f9 100644 --- a/.github/workflows/clang.yml +++ b/.github/workflows/clang.yml @@ -9,10 +9,6 @@ jobs: lint: name: Clang Format Lint runs-on: ubuntu-latest - strategy: - fail-fast: false # false to test all, true to fail entire job if any fail - matrix: - inplace: [ true, false ] # removed ubuntu_18_04 for now steps: - name: Checkout @@ -25,10 +21,10 @@ jobs: extensions: 'cpp,h,m,mm' clangFormatVersion: 13 style: file - inplace: ${{ matrix.inplace }} + inplace: false - name: Upload Artifacts - if: ${{ matrix.inplace == true }} + if: failure() uses: actions/upload-artifact@v3 with: name: sunshine diff --git a/.github/workflows/localize.yml b/.github/workflows/localize.yml index 57db544a..b860ad64 100644 --- a/.github/workflows/localize.yml +++ b/.github/workflows/localize.yml @@ -3,15 +3,16 @@ name: localize on: push: branches: [nightly] - paths: # prevents workflow from running unless files in these directories change - - 'sunshine/**' # only localizing files inside sunshine directory + paths: # prevents workflow from running unless these files change + - 'sunshine/**' + - 'locale/sunshine.po' workflow_dispatch: jobs: localize: name: Update Localization - if: ${{ github.event.pull_request.merged }} runs-on: ubuntu-latest + steps: - name: Checkout uses: actions/checkout@v3 @@ -37,9 +38,37 @@ jobs: run: | python ./scripts/_locale.py --extract - - name: GitHub Commit & Push # push changes back into nightly - uses: actions-js/push@v1.3 + - name: git diff + run: | + # print the git diff + git diff --exit-code locale/sunshine.po + + # set the variable with minimal output + OUTPUT=$(git diff --exit-code --numstat locale/sunshine.po) + echo "git_diff=${OUTPUT}" >> $GITHUB_ENV + + - name: git reset + if: ${{ env.git_diff != '1 1 locale/sunshine.po' }} # only run if more than 1 line changed + run: | + git reset --hard + + - name: Create/Update Pull Request + uses: peter-evans/create-pull-request@v4 with: - github_token: ${{ secrets.GITHUB_TOKEN }} - branch: nightly - message: localization updated by localize workflow + add-paths: | + locale/*.po + token: ${{ secrets.GH_PAT }} # must trigger PR tests + commit-message: New localization template + branch: localize/update + delete-branch: true + base: nightly + title: New Babel Updates + body: | + Update report + - Updated with *today's* date + - Auto-generated by [create-pull-request][1] + + [1]: https://github.com/peter-evans/create-pull-request + labels: | + babel + l10n diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..78c304f8 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,26 @@ +# .readthedocs.yaml +# 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-20.04 + tools: + python: "3.9" + +# 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: ./scripts/requirements.txt + system_packages: true diff --git a/DOCKER_README.md b/DOCKER_README.md new file mode 100644 index 00000000..8691e01b --- /dev/null +++ b/DOCKER_README.md @@ -0,0 +1,113 @@ +# Docker + +## Using docker run +Create and run the container (substitute your ``): + +```bash +docker run -d \ + --name=sunshine \ + --restart=unless-stopped + -v :/config \ + -e PUID= \ + -e PGID= \ + -e TZ= \ + -p 47990:47990 \ + -p 47984:47984 \ + -p 47989:47989 \ + -p 48010:48010 \ + -p 47998:47998 \ + -p 47999:47999 \ + -p 48000:48000 \ + -p 48002:48002 \ + -p 48010:48010 \ + sunshinestream/sunshine +``` + +To update the container it must be removed and recreated: + +```bash +# Stop the container +docker stop sunshine +# Remove the container +docker rm sunshine +# Pull the latest update +docker pull sunshinestream/sunshine +# Run the container with the same parameters as before +docker run -d ... +``` + +## Using docker-compose + +Create a `docker-compose.yml` file with the following contents (substitute your ``): + +```yaml +version: '3' +services: + retroarcher: + image: sunshinestream/sunshine + container_name: sunshine + restart: unless-stopped + volumes: + - :/config + environment: + - PUID= + - PGID= + - TZ= + ports: + - "47990:47990" + - "47984:47984" + - "47989:47989" + - "48010:48010" + - "47998:47998" + - "47999:47999" + - "48000:48000" + - "48002:48002" + - "48010:48010" +``` + +Create and start the container (run the command from the same folder as your `docker-compose.yml` file): + +```bash +docker-compose up -d +``` + +To update the container: +```bash +# Pull the latest update +docker-compose pull +# Update and restart the container +docker-compose up -d +``` + +## Parameters +You must substitute the `` with your own settings. + +Parameters are split into two halves separated by a colon. The left side represents the host and the right side the +container. + +**Example:** `-p external:internal` - This shows the port mapping from internal to external of the container. +Therefore `-p 47990:47990` would expose port `47990` from inside the container to be accessible from the host's IP on +port `47990` (e.g. `http://:47990`). The internal port must be `47990`, but the external port may be changed +(e.g. `-p 8080:47990`). + + +| Parameter | Function | Example Value | Required | +| --------------------------- | -------------------- | ------------------- | -------- | +| `-p :47990` | Web UI Port | `47990` | True | +| `-v :/config` | Volume mapping | `/home/sunshine` | True | +| `-e PUID=` | User ID | `1001` | False | +| `-e PGID=` | Group ID | `1001` | False | +| `-e TZ=` | Lookup TZ value [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | `America/New_York` | True | + +### User / Group Identifiers: + +When using data volumes (-v flags) permissions issues can arise between the host OS and the container. To avoid this +issue you can specify the user PUID and group PGID. Ensure the data volume directory on the host is owned by the same +user you specify. + +In this instance `PUID=1001` and `PGID=1001`. To find yours use id user as below: + +```bash +$ id dockeruser +uid=1001(dockeruser) gid=1001(dockergroup) groups=1001(dockergroup) +``` diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..8fb29b6b --- /dev/null +++ b/README.rst @@ -0,0 +1,65 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/README.rst + +Overview +======== + +About +----- +Sunshine is a Game stream host for Moonlight. It is an open source version of GeForce Experience (GFE). + +These are the advantages of Sunshine over GFE. + + - FOSS (Free and Open Source Software) + - Multi-platform + + - Linux (deb, rpm, and AppImage packages) + - MacOS (Portfile) + - Windows (portable binary) + + - Pair over web ui + - Supports AMD and Nvidia GPUs for encoding + - Supports software encoding + - Supports streaming to multiple clients + - Web UI for configuration + +Integrations +------------ + +.. image:: https://img.shields.io/github/workflow/status/sunshinestream/sunshine/CI/master?label=CI%20build&logo=github&style=for-the-badge + :alt: GitHub Workflow Status (CI) + :target: https://github.com/SunshineStream/Sunshine/actions/workflows/CI.yml?query=branch%3Amaster + +.. image:: https://img.shields.io/github/workflow/status/sunshinestream/sunshine/localize/nightly?label=localize%20build&logo=github&style=for-the-badge + :alt: GitHub Workflow Status (localize) + :target: https://github.com/SunshineStream/Sunshine/actions/workflows/localize.yml?query=branch%3Anightly + +.. image:: https://img.shields.io/readthedocs/sunshinestream?label=Docs&style=for-the-badge&logo=readthedocs + :alt: Read the Docs + :target: http://sunshinestream.readthedocs.io/ + +.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=localized&style=for-the-badge&query=%24.progress..data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json&logo=crowdin + :alt: CrowdIn + :target: https://crowdin.com/project/sunshinestream + +Support +--------- + +.. image:: https://img.shields.io/discord/938534566107418705?label=Discord&style=for-the-badge&color=blue&logo=discord + :alt: Discord + :target: https://sunshinestream.github.io/discord + +.. image:: https://img.shields.io/github/discussions/sunshinestream/sunshine?logo=github&style=for-the-badge + :alt: GitHub Discussions + :target: https://github.com/SunshineStream/Sunshine/discussions + +Downloads +--------- + +.. image:: https://img.shields.io/github/downloads/sunshinestream/sunshine/total?style=for-the-badge&logo=github + :alt: GitHub Releases + :target: https://github.com/SunshineStream/Sunshine/releases/latest + +.. comment + image:: https://img.shields.io/docker/pulls/sunshinestream/sunshine?style=for-the-badge&logo=docker + :alt: Docker + :target: https://hub.docker.com/r/sunshinestream/sunshine diff --git a/assets/sunshine.conf b/assets/sunshine.conf index a1e020f0..509ff52a 100644 --- a/assets/sunshine.conf +++ b/assets/sunshine.conf @@ -1,318 +1 @@ -# If no external IP address is given, Sunshine will attempt to automatically detect external ip-address -# external_ip = 123.456.789.12 - -# Set the familly of ports used by Sunshine -# port = 47989 - -# The private key must be 2048 bits -# pkey = /dir/pkey.pem - -# The certificate must be signed with a 2048 bit key -# cert = /dir/cert.pem - -# The name displayed by Moonlight -# If not specified, the PC's hostname is used -# sunshine_name = Sunshine - -# The minimum log level printed to standard out -# -# none -> no logs are printed to standard out -# -# verbose = [0] -# debug = [1] -# info = [2] -# warning = [3] -# error = [4] -# fatal = [5] -# none = [6] -# -# min_log_level = info - -# The origin of the remote endpoint address that is not denied for HTTP method /pin -# Could be any of the following values: -# pc|lan|wan -# pc: Only localhost may access /pin -# lan: Only those in LAN may access /pin -# wan: Anyone may access /pin -# -# origin_pin_allowed = pc - -# The origin of the remote endpoint address that is not denied for HTTPS Web UI -# Could be any of the following values: -# pc|lan|wan -# pc: Only localhost may access the Web Manager -# lan: Only those in LAN may access the Web Manager -# wan: Anyone may access the Web Manager -# -# origin_web_ui_allowed = lan - -# If UPnP is enabled, Sunshine will attempt to open ports for streaming over the internet -# To enable it, uncomment the following line: -# upnp = on - -# The file where current state of Sunshine is stored -# file_state = sunshine_state.json - -# The file where user credentials for the UI are stored -# By default, credentials are stored in `file_state` -# credentials_file = sunshine_state.json - -# The display modes advertised by Sunshine -# -# Some versions of Moonlight, such as Moonlight-nx (Switch), -# rely on this list to ensure that the requested resolutions and fps -# are supported. -# -# fps = [10, 30, 60, 90, 120] -# resolutions = [ -# 352x240, -# 480x360, -# 858x480, -# 1280x720, -# 1920x1080, -# 2560x1080, -# 3440x1440, -# 1920x1200, -# 3860x2160, -# 3840x1600, -# ] - -# Sometimes it may be usefull to map keybindings. -# Wayland won't allow clients to capture the Win Key for example -# -# See https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes -# -# Note: -# keybindings needs to have a multiple of two elements -# keybindings = [ -# 0x10, 0xA0, -# 0x11, 0xA2, -# 0x12, 0xA4, -# 0x4A, 0x4B -# ] - -# It may be possible that you cannot send the Windows Key from Moonlight directly. -# In those cases it may be useful to make Sunshine think the Right Alt key is the Windows key -# key_rightalt_to_key_win = enabled - -# How long to wait in milliseconds for data from moonlight before shutting down the stream -# ping_timeout = 10000 - -# The file where configuration for the different applications that Sunshine can run during a stream -# file_apps = apps.json - -# Percentage of error correcting packets per data packet in each video frame -# Higher values can correct for more network packet loss, but at the cost of increasing bandwidth usage -# The default value of 20 is what GeForce Experience uses -# -# The value must be greater than 0 and lower than or equal to 255 -# fec_percentage = 20 - -# When multicasting, it could be usefull to have different configurations for each connected Client. -# For example: -# Clients connected through WAN and LAN have different bitrate contstraints. -# Decoders may require different settings for color -# -# Unlike simply broadcasting to multiple Client, this will generate distinct video streams. -# Note, CPU usage increases for each distinct video stream generated -# channels = 1 - -# The back/select button on the controller -# On the Shield, the home and powerbutton are not passed to Moonlight -# If, after the timeout, the back button is still pressed down, Home/Guide button press is emulated. -# If back_button_timeout < 0, then the Home/Guide button will not be emulated -# back_button_timeout = 2000 - -# !! Windows only !! -# Gamepads supported by Sunshine -# Possible values: -# x360 -- xbox 360 controller -# ds4 -- dualshock controller (PS4) -# gamepad = x360 - -# Control how fast keys will repeat themselves -# The initial delay in milliseconds before repeating keys -# key_repeat_delay = 500 -# -# How often keys repeat every second -# This configurable option supports decimals -# key_repeat_frequency = 24.9 - -# The name of the audio sink used for Audio Loopback -# If you do not specify this variable, pulseaudio will select the default monitor device. -# -# You can find the name of the audio sink using the following command: -# !! Linux only !! -# pacmd list-sinks | grep "name:" if running vanilla pulseaudio -# pPipewire: Use `pactl info | grep Source`. In some causes you'd need to use the `sink` device. Try `pactl info | grep Sink`, if _Source_ doesn't work -# audio_sink = alsa_output.pci-0000_09_00.3.analog-stereo -# -# !! Windows only !! -# tools\audio-info.exe -# audio_sink = {0.0.0.00000000}.{FD47D9CC-4218-4135-9CE2-0C195C87405B} -# -# The virtual sink, is the audio device that's virtual (Like Steam Streaming Speakers), it allows Sunshine -# to stream audio, while muting the speakers. -# virtual_sink = {0.0.0.00000000}.{8edba70c-1125-467c-b89c-15da389bc1d4} - -# -# !! MacOS only !! -# audio_sink = BlackHole 2ch - -# !! Windows only !! -# You can select the video card you want to stream: -# The appropriate values can be found using the following command: -# tools\dxgi-info.exe -# adapter_name = Radeon RX 580 Series -# output_name = \\.\DISPLAY1 - -# !! Linux only !! -# Set the display number to stream. -# You can find them by the following command: -# xrandr --listmonitors -# Example output: "0: +HDMI-1 1920/518x1200/324+0+0 HDMI-1" -# ^ <-- You need this. -# output_name = 0 - -############################################### -# FFmpeg software encoding parameters -# Honestly, I have no idea what the optimal values would be. -# Play around with this :) - -# Quantitization Parameter -# Some devices don't support Constant Bit Rate. For those devices, QP is used instead -# Higher value means more compression, but less quality -# qp = 28 - -# Minimum number of threads used by ffmpeg to encode the video. -# Increasing the value slightly reduces encoding efficiency, but the tradeoff is usually -# worth it to gain the use of more CPU cores for encoding. The ideal value is the lowest -# value that can reliably encode at your desired streaming settings on your hardware. -# min_threads = 1 - -# Allows the client to request HEVC Main or HEVC Main10 video streams. -# HEVC is more CPU-intensive to encode, so enabling this may reduce performance when using software encoding. -# If set to 0 (default), Sunshine will specify support for HEVC based on encoder -# If set to 1, Sunshine will not advertise support for HEVC -# If set to 2, Sunshine will advertise support for HEVC Main profile -# If set to 3, Sunshine will advertise support for HEVC Main and Main10 (HDR) profiles -# hevc_mode = 2 - -# Force a specific encoder, otherwise Sunshine will use the first encoder that is available -# supported encoders: -# nvenc -# amdvce # NOTE: alpha stage. The cursor is not yet displayed -# software -# -# encoder = nvenc -##################################### Software ##################################### -# See x264 --fullhelp for the different presets -# sw_preset = superfast -# sw_tune = zerolatency -# - -##################################### NVENC ##################################### -###### presets ########### -# default -# hp -- high performance -# hq -- high quality -# slow -- hq 2 passes -# medium -- hq 1 pass -# fast -- hp 1 pass -# bd -# ll -- low latency -# llhq -# llhp -# lossless -# losslesshp -########################## -# nv_preset = llhq -# -####### rate control ##### -# auto -- let ffmpeg decide rate control -# constqp -- constant QP mode -# vbr -- variable bitrate -# cbr -- constant bitrate -# cbr_hq -- cbr high quality -# cbr_ld_hq -- cbr low delay high quality -# vbr_hq -- vbr high quality -########################## -# nv_rc = auto - -###### h264 entropy ###### -# auto -- let ffmpeg nvenc decide the entropy encoding -# cabac -# cavlc -########################## -# nv_coder = auto - -##################################### AMD ##################################### -###### presets ########### -# default -# speed -# balanced -########################## -# amd_quality = balanced -# -####### rate control ##### -# auto -- let ffmpeg decide rate control -# constqp -- constant QP mode -# vbr_latency -- Latency Constrained Variable Bitrate -# vbr_peak -- Peak Contrained Variable Bitrate -# cbr -- constant bitrate -########################## -# amd_rc = auto - -###### h264 entropy ###### -# auto -- let ffmpeg nvenc decide the entropy encoding -# cabac -# cavlc -########################## -# amd_coder = auto - -#################################### VAAPI ################################### -####### adapter ########## -# Unlike with `amdvce` and `nvenc`, it doesn't matter if video encoding is done -# on a different GPU. -# Run the following commands: -# 1. ls /dev/dri/renderD* -# to find all devices capable of VAAPI -# 2. vainfo --display drm --device /dev/dri/renderD129 | grep -E "((VAProfileH264High|VAProfileHEVCMain|VAProfileHEVCMain10).*VAEntrypointEncSlice)|Driver version" -# Lists the name and capabilities of the device. -# To be supported by Sunshine, it needs to have at the very minimum: -# VAProfileH264High : VAEntrypointEncSlice -# adapter_name = /dev/dri/renderD128 - -################################# VideoToolbox ############################### -####### software encoding ########## -# Video Toolbox can be allowed/required to use software encoding instead of -# hardware accelerated encoding. -# auto -- let sunshine decide on encoding -# disabled -- disable software encoding -# allowed -- allow software encoding -# forced -- force software encoding -########################## -# vt_software = auto -# -####### realtime encoding ########## -# Disabling realtime encoding might result in a delayed frame encoding or frame drop -########################## -# vt_realtime = enabled -# -###### h264/hevc entropy ###### -# auto -- let ffmpeg decide the entropy encoding -# cabac -# cavlc -########################## -# vt_coder = auto - - -############################################## -# Some configurable parameters, are merely toggles for specific features -# The first occurrence turns it on, the second occurence turns it off, the third occurence turns it on again, etc, etc -# Here, you change the default state of any flag -# -# To set the initial state of flags -0 and -1 to on, set the following flags: -# flags = 012 -# -# See: sunshine --help for all options under the header: flags +# See our documentation at https://sunshinestream.readthedocs.io/en/latest/about/advanced_usage.html diff --git a/crowdin.yml b/crowdin.yml index d014a00c..ca9c8c5c 100644 --- a/crowdin.yml +++ b/crowdin.yml @@ -1,6 +1,10 @@ "base_path": "." "base_url": "https://api.crowdin.com" # optional (for Crowdin Enterprise only) "preserve_hierarchy": false # flatten tree on crowdin +"pull_request_labels": [ + "crowdin", + "l10n" +] "files" : [ { diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..dc1312ab --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%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% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/about/advanced_usage.rst b/docs/source/about/advanced_usage.rst new file mode 100644 index 00000000..e01de0aa --- /dev/null +++ b/docs/source/about/advanced_usage.rst @@ -0,0 +1,1087 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/about/advanced_usage.rst + +Advanced Usage +============== +Sunshine will work with the default settings for most users. In some cases you may want to configure Sunshine further. + +Configuration +------------- +The default location for the configuration file is ``./assets/sunshine.conf``. You can use another location if you +choose, by passing in the full configuration file path as the first argument when you start Sunshine. + +** Default File Location** + +.. table:: + :widths: auto + + ======= =========== + Value Description + ======= =========== + Linux ./assets/sunshine.conf + MacOS /opt/local/etc/sunshine.conf + Windows ./assets/sunshine.conf + ======= =========== + +Example + .. code-block:: bash + + sunshine ~/sunshine_config.conf + +To manually configure sunshine you may edit the `conf` file in a text editor. Use the examples as reference. + +.. Note:: Some settings are not available within the web ui. + +General +------- + +sunshine_name +^^^^^^^^^^^^^ + +Description + The name displayed by Moonlight + +Default + PC hostname + +Example + .. code-block:: text + + sunshine_name = Sunshine + +min_log_level +^^^^^^^^^^^^^ + +Description + The minimum log level printed to standard out. + +**Choices** + +.. table:: + :widths: auto + + ======= =========== + Value Description + ======= =========== + verbose verbose logging + debug debug logging + info info logging + warning warning logging + error error logging + fatal fatal logging + none no logging + ======= =========== + +Default + ``info`` + +Example + .. code-block:: text + + min_log_level = info + +Controls +-------- + +gamepad +^^^^^^^ + +Description + The type of gamepad to emulate on the host. + + .. Caution:: Applies to Windows only. + +**Choices** + +.. table:: + :widths: auto + + ===== =========== + Value Description + ===== =========== + x360 xbox 360 controller + ds4 dualshock controller (PS4) + ===== =========== + +Default + ``x360`` + +Example + .. code-block:: text + + gamepad = x360 + +back_button_timeout +^^^^^^^^^^^^^^^^^^^ + +Description + If, after the timeout, the back/select button is still pressed down, Home/Guide button press is emulated. + + On Nvidia Shield, the home and power button are not passed to Moonlight. + + .. Tip:: If back_button_timeout < 0, then the Home/Guide button will not be emulated. + +Default + ``2000`` + +Example + .. code-block:: text + + back_button_timeout = 2000 + +key_repeat_delay +^^^^^^^^^^^^^^^^ + +Description + The initial delay in milliseconds before repeating keys. Controls how fast keys will repeat themselves. + +Default + ``500`` + +Example + .. code-block:: text + + key_repeat_delay = 500 + +key_repeat_frequency +^^^^^^^^^^^^^^^^^^^^ + +Description + How often keys repeat every second. + + .. Tip:: This configurable option supports decimals. + +Default + .. Todo:: Unknown + +Example + .. code-block:: text + + key_repeat_frequency = 24.9 + +keybindings +^^^^^^^^^^^ + +Description + Sometimes it may be useful to map keybindings. Wayland won't allow clients to capture the Win Key for example. + + .. Tip:: See `virtual key codes `_ + + .. Note:: keybindings needs to have a multiple of two elements. + +Default + None + +Example + .. code-block:: text + + keybindings = [ + 0x10, 0xA0, + 0x11, 0xA2, + 0x12, 0xA4, + 0x4A, 0x4B + ] + +key_rightalt_to_key_win +^^^^^^^^^^^^^^^^^^^^^^^ + +Description + It may be possible that you cannot send the Windows Key from Moonlight directly. In those cases it may be useful to + make Sunshine think the Right Alt key is the Windows key. + +Default + None + +Example + .. code-block:: text + + key_rightalt_to_key_win = enabled + +Display +------- + +adapter_name +^^^^^^^^^^^^ + +Description + Select the video card you want to stream. + + .. Tip:: To find the name of the appropriate values follow these instructions. + + Linux + VA-API + Unlike with `amdvce` and `nvenc`, it doesn't matter if video encoding is done on a different GPU. + + .. code-block:: bash + + ls /dev/dri/renderD* # to find all devices capable of VAAPI + + # replace ``renderD129`` with the device from above to lists the name and capabilities of the device + vainfo --display drm --device /dev/dri/renderD129 | \ + grep -E "((VAProfileH264High|VAProfileHEVCMain|VAProfileHEVCMain10).*VAEntrypointEncSlice)|Driver version" + + To be supported by Sunshine, it needs to have at the very minimum: + ``VAProfileH264High : VAEntrypointEncSlice`` + + .. Todo:: MacOS + + Windows + .. code-block:: batch + + tools\dxgi-info.exe + +Default + Sunshine will select the default video card. + +Examples + Linux + .. code-block:: text + + adapter_name = /dev/dri/renderD128 + + .. Todo:: MacOS + + Windows + .. code-block:: text + + adapter_name = Radeon RX 580 Series + +output_name +^^^^^^^^^^^ + +Description + Select the display number you want to stream. + + .. Tip:: To find the name of the appropriate values follow these instructions. + + Linux + .. code-block:: bash + + xrandr --listmonitors + + Example output: ``0: +HDMI-1 1920/518x1200/324+0+0 HDMI-1`` + + You need to use the value before the colon in the output, e.g. ``0``. + + .. Todo:: MacOS + + Windows + .. code-block:: batch + + tools\dxgi-info.exe + +Default + Sunshine will select the default display. + +Examples + Linux + .. code-block:: text + + output_name = 0 + + .. Todo:: MacOS + + Windows + .. code-block:: text + + output_name = \\.\DISPLAY1 + +fps +^^^ + +Description + The fps modes advertised by Sunshine. + + .. Note:: Some versions of Moonlight, such as Moonlight-nx (Switch), rely on this list to ensure that the requested + fps is supported. + +Default + .. Todo:: Unknown + +Example + .. code-block:: text + + fps = [10, 30, 60, 90, 120] + +resolutions +^^^^^^^^^^^ + +Description + The resolutions advertised by Sunshine. + + .. Note:: Some versions of Moonlight, such as Moonlight-nx (Switch), rely on this list to ensure that the requested + resolution is supported. + +Default + .. Todo:: Unknown + +Example + .. code-block:: text + + resolutions = [ + 352x240, + 480x360, + 858x480, + 1280x720, + 1920x1080, + 2560x1080, + 3440x1440, + 1920x1200, + 3860x2160, + 3840x1600, + ] + +Audio +----- + +audio_sink +^^^^^^^^^^ + +Description + The name of the audio sink used for audio loopback. + + .. Tip:: To find the name of the audio sink follow these instructions. + + Linux + pulseaudio + .. code-block:: bash + + pacmd list-sinks | grep "name:" + + Linux + pipewire + .. code-block:: bash + + pactl info | grep Source + # in some causes you'd need to use the `Sink` device, if `Source` doesn't work, so try: + pactl info | grep Sink + + MacOS + Sunshine can only access microphones on MacOS due to system limitations. To stream system audio use + `Soundflower `_ or + `BlackHole `_. + + Windows + .. code-block:: batch + + tools\audio-info.exe + +Default + Sunshine will select the default audio device. + +Examples + Linux + .. code-block:: text + + audio_sink = alsa_output.pci-0000_09_00.3.analog-stereo + + MacOS + .. code-block:: text + + audio_sink = BlackHole 2ch + + Windows + .. code-block:: text + + audio_sink = {0.0.0.00000000}.{FD47D9CC-4218-4135-9CE2-0C195C87405B} + +virtual_sink +^^^^^^^^^^^^ + +Description + The audio device that's virtual, like Steam Streaming Speakers. This allows Sunshine to stream audio, while muting + the speakers. + + .. Tip:: See `audio_sink`_! + +Default + .. Todo:: Unknown + +Example + .. code-block:: text + + virtual_sink = {0.0.0.00000000}.{8edba70c-1125-467c-b89c-15da389bc1d4} + +Network +------- + +external_ip +^^^^^^^^^^^ + +Description + If no external IP address is given, Sunshine will attempt to automatically detect external ip-address. + +Default + Automatic + +Example + .. code-block:: text + + external_ip = 123.456.789.12 + +port +^^^^ + +Description + Set the family of ports used by Sunshine. + +Default + ``47989`` + +Example + .. code-block:: text + + port = 47989 + +pkey +^^^^ + +Description + The private key. This must be 2048 bits. + +Default + .. Todo:: Unknown + +Example + .. code-block:: text + + pkey = /dir/pkey.pem + +cert +^^^^ + +Description + The certificate. Must be signed with a 2048 bit key. + +Default + .. Todo:: Unknown + +Example + .. code-block:: text + + cert = /dir/cert.pem + +origin_pin_allowed +^^^^^^^^^^^^^^^^^^ + +Description + The origin of the remote endpoint address that is not denied for HTTP method /pin. + +**Choices** + +.. table:: + :widths: auto + + ===== =========== + Value Description + ===== =========== + pc Only localhost may access /pin + lan Only LAN devices may access /pin + wan Anyone may access /pin + ===== =========== + +Default + ``pc`` + +Example + .. code-block:: text + + origin_pin_allowed = pc + +origin_web_ui_allowed +^^^^^^^^^^^^^^^^^^^^^ + +Description + The origin of the remote endpoint address that is not denied for HTTPS Web UI. + +**Choices** + +.. table:: + :widths: auto + + ===== =========== + Value Description + ===== =========== + pc Only localhost may access the web ui + lan Only LAN devices may access the web ui + wan Anyone may access the web ui + ===== =========== + +Default + ``lan`` + +Example + .. code-block:: text + + origin_web_ui_allowed = lan + +upnp +^^^^ + +Description + Sunshine will attempt to open ports for streaming over the internet. + +**Choices** + +.. table:: + :widths: auto + + ===== =========== + Value Description + ===== =========== + on enable UPnP + off disable UPnP + ===== =========== + +Default + ``off`` + +Example + .. code-block:: text + + upnp = on + +ping_timeout +^^^^^^^^^^^^ + +Description + How long to wait in milliseconds for data from Moonlight before shutting down the stream. + +Default + ``10000`` + +Example + .. code-block:: text + + ping_timeout = 10000 + +Encoding +-------- + +channels +^^^^^^^^ + +Description + This will generate distinct video streams, unlike simply broadcasting to multiple Clients. + + When multicasting, it could be useful to have different configurations for each connected Client. + + For instance: + + - Clients connected through WAN and LAN have different bitrate constraints. + - Decoders may require different settings for color. + + .. Warning:: CPU usage increases for each distinct video stream generated. + +Default + ``1`` + +Example + .. code-block:: text + + channels = 1 + +fec_percentage +^^^^^^^^^^^^^^ + +Description + Percentage of error correcting packets per data packet in each video frame. + + .. Warning:: Higher values can correct for more network packet loss, but at the cost of increasing bandwidth usage. + +Default + ``20`` + +Range + ``1-255`` + +Example + .. code-block:: text + + fec_percentage = 20 + +qp +^^ + +Description + Quantitization Parameter. Some devices don't support Constant Bit Rate. For those devices, QP is used instead. + + .. Warning:: Higher value means more compression, but less quality. + +Default + ``28`` + +Example + .. code-block:: text + + qp = 28 + +min_threads +^^^^^^^^^^^ + +Description + Minimum number of threads used by ffmpeg to encode the video. + + .. Note:: Increasing the value slightly reduces encoding efficiency, but the tradeoff is usually worth it to gain + the use of more CPU cores for encoding. The ideal value is the lowest value that can reliably encode at your + desired streaming settings on your hardware. + +Default + ``1`` + +Example + .. code-block:: text + + min_threads = 1 + +hevc_mode +^^^^^^^^^ + +Description + Allows the client to request HEVC Main or HEVC Main10 video streams. + + .. Warning:: HEVC is more CPU-intensive to encode, so enabling this may reduce performance when using software + encoding. + +**Choices** + +.. table:: + :widths: auto + + ===== =========== + Value Description + ===== =========== + 0 advertise support for HEVC based on encoder + 1 do not advertise support for HEVC + 2 advertise support for HEVC Main profile + 3 advertise support for HEVC Main and Main10 (HDR) profiles + ===== =========== + +Default + ``0`` + +Example + .. code-block:: text + + hevc_mode = 2 + +encoder +^^^^^^^ + +Description + Force a specific encoder. + +**Choices** + +.. table:: + :widths: auto + + ======== =========== + Value Description + ======== =========== + nvenc For Nvidia graphics cards + amdvce For AMD graphics cards + software Encoding occurs on the CPU + ======== =========== + +Default + Sunshine will use the first encoder that is available. + +Example + .. code-block:: text + + encoder = nvenc + +sw_preset +^^^^^^^^^ + +Description + The encoder preset to use. + + .. Note:: This option only applies when using software `encoder`_. + + .. Note:: From `FFmpeg `_. + + A preset is a collection of options that will provide a certain encoding speed to compression ratio. A slower + preset will provide better compression (compression is quality per filesize). This means that, for example, if + you target a certain file size or constant bit rate, you will achieve better quality with a slower preset. + Similarly, for constant quality encoding, you will simply save bitrate by choosing a slower preset. + + Use the slowest preset that you have patience for. + +**Choices** + +.. table:: + :widths: auto + + ========= =========== + Value Description + ========= =========== + ultrafast fastest + superfast + veryfast + superfast + faster + fast + medium + slow + slow + slower + veryslow slowest + ========= =========== + +Default + ``superfast`` + +Example + .. code-block:: text + + sw_preset = superfast + +sw_tune +^^^^^^^ + +Description + The tuning preset to use. + + .. Note:: This option only applies when using software `encoder`_. + + .. Note:: From `FFmpeg `_. + + You can optionally use -tune to change settings based upon the specifics of your input. + +**Choices** + +.. table:: + :widths: auto + + =========== =========== + Value Description + =========== =========== + film use for high quality movie content; lowers deblocking + animation good for cartoons; uses higher deblocking and more reference frames + grain preserves the grain structure in old, grainy film material + stillimage good for slideshow-like content + fastdecode allows faster decoding by disabling certain filters + zerolatency good for fast encoding and low-latency streaming + =========== =========== + +Default + ``zerolatency`` + +Example + .. code-block:: text + + sw_tune = zerolatency + +nv_preset +^^^^^^^^^ + +Description + The encoder preset to use. + + .. Note:: This option only applies when using nvenc `encoder`_. + +**Choices** + +.. table:: + :widths: auto + + ========== =========== + Value Description + ========== =========== + default let ffmpeg decide + hp high performance + hq high quality + slow high quality, 2 passes + medium high quality, 1 pass + fast high performance, 1 pass + bd + ll low latency + llhq low latency, high quality + llhp low latency, high performance + lossless lossless + losslesshp lossless, high performance + ========== =========== + +Default + ``llhq`` + +Example + .. code-block:: text + + nv_preset = llhq + +nv_rc +^^^^^ + +Description + The encoder rate control. + + .. Note:: This option only applies when using nvenc `encoder`_. + + .. Note:: Moonlight does not currently support variable bitrate, although it can still be selected here. + +**Choices** + +.. table:: + :widths: auto + + ========== =========== + Value Description + ========== =========== + auto let ffmpeg decide + constqp constant QP mode + cbr constant bitrate + cbr_hq constant bitrate, high quality + cbr_ld_hq constant bitrate, low delay, high quality + vbr variable bitrate + vbr_hq variable bitrate, high quality + ========== =========== + +Default + ``auto`` + +Example + .. code-block:: text + + nv_rc = auto + +nv_coder +^^^^^^^^ + +Description + The entropy encoding to use. + + .. Note:: This option only applies when using nvenc `encoder`_. + +**Choices** + +.. table:: + :widths: auto + + ========== =========== + Value Description + ========== =========== + auto let ffmpeg decide + cabac + cavlc + ========== =========== + +Default + ``auto`` + +Example + .. code-block:: text + + nv_coder = auto + +amd_quality +^^^^^^^^^^^ + +Description + The encoder preset to use. + + .. Note:: This option only applies when using amdvce `encoder`_. + +**Choices** + +.. table:: + :widths: auto + + ========== =========== + Value Description + ========== =========== + default let ffmpeg decide + speed fast + balanced balance performance and speed + ========== =========== + +Default + ``balanced`` + +Example + .. code-block:: text + + amd_quality = balanced + +amd_rc +^^^^^^ + +Description + The encoder rate control. + + .. Note:: This option only applies when using amdvce `encoder`_. + + .. Note:: Moonlight does not currently support variable bitrate, although it can still be selected here. + +**Choices** + +.. table:: + :widths: auto + + =========== =========== + Value Description + =========== =========== + auto let ffmpeg decide + constqp constant QP mode + cbr constant bitrate + vbr_latency variable bitrate, latency constrained + vbr_peak variable bitrate, peak constrained + =========== =========== + +Default + ``auto`` + +Example + .. code-block:: text + + amd_rc = auto + +amd_coder +^^^^^^^^^ + +Description + The entropy encoding to use. + + .. Note:: This option only applies when using nvenc `encoder`_. + +**Choices** + +.. table:: + :widths: auto + + ========== =========== + Value Description + ========== =========== + auto let ffmpeg decide + cabac + cavlc + ========== =========== + +Default + ``auto`` + +Example + .. code-block:: text + + amd_coder = auto + +vt_software +^^^^^^^^^^^ + +Description + Force Video Toolbox to use software encoding. + + .. Note:: This option only applies when using MacOS. + +**Choices** + +.. table:: + :widths: auto + + ========== =========== + Value Description + ========== =========== + auto let ffmpeg decide + disabled disable software encoding + allowed allow software encoding + forced force software encoding + ========== =========== + +Default + ``auto`` + +Example + .. code-block:: text + + vt_software = auto + +vt_realtime +^^^^^^^^^^^ + +Description + Realtime encoding. + + .. Note:: This option only applies when using MacOS. + + .. Warning:: Disabling realtime encoding might result in a delayed frame encoding or frame drop. + +Default + ``enabled`` + +Example + .. code-block:: text + + vt_realtime = enabled + +vt_coder +^^^^^^^^ + +Description + The entropy encoding to use. + + .. Note:: This option only applies when using MacOS. + +**Choices** + +.. table:: + :widths: auto + + ========== =========== + Value Description + ========== =========== + auto let ffmpeg decide + cabac + cavlc + ========== =========== + +Default + ``auto`` + +Example + .. code-block:: text + + vt_coder = auto + +Advanced +-------- + +file_apps +^^^^^^^^^ + +Description + The application configuration file path. The file contains a json formatted list of applications that can be started + by Moonlight. + +Default + OS dependent + +Example + .. code-block:: text + + file_apps = apps.json + +file_state +^^^^^^^^^^ + +Description + The file where current state of Sunshine is stored. + +Default + ``sunshine_state.json`` + +Example + .. code-block:: text + + file_state = sunshine_state.json + +credentials_file +^^^^^^^^^^^^^^^^ + +Description + The file where user credentials for the UI are stored. + +Default + ``sunshine_state.json`` + +Example + .. code-block:: text + + credentials_file = sunshine_state.json diff --git a/docs/source/about/docker.rst b/docs/source/about/docker.rst new file mode 100644 index 00000000..f9afa251 --- /dev/null +++ b/docs/source/about/docker.rst @@ -0,0 +1,5 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/DOCKER_README.md + +.. Todo:: This is a planned feature. Currently no Dockerfile or image exists for Sunshine. + +.. mdinclude:: ../../../DOCKER_README.md diff --git a/docs/source/about/installation.rst b/docs/source/about/installation.rst new file mode 100644 index 00000000..14ee37d2 --- /dev/null +++ b/docs/source/about/installation.rst @@ -0,0 +1,84 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/about/installation.rst + +Installation +============ +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, and Windows. +Binaries can be found in the `latest release`_. + +.. Todo:: Create binary package(s) for MacOS. See `here `_. + +.. Tip:: Some third party packages also exist. See + :ref:`Third Party Packages `. + +Docker +------ +.. Todo:: Docker images of Sunshine are planned to be included in the future. + They will be available on `Dockerhub.io`_ and `ghcr.io`_. + +Linux +----- + +AppImage +^^^^^^^^ +.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/pkg:appimage?logo=github&style=for-the-badge' + :alt: GitHub issues by-label + +#. Download and extract `sunshine-appimage.zip` + +Debian Packages +^^^^^^^^^^^^^^^ +.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:linux:debian?logo=github&style=for-the-badge' + :alt: GitHub issues by-label + +#. Download the corresponding `.deb` file, e.g. ``sunshine-ubuntu_20_04.deb`` +#. ``sudo apt install -f ``, e.g. ``sudo apt install -f ./sunshine-ubuntu_20_04.deb`` + +Red Hat Packages +^^^^^^^^^^^^^^^^ +.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:linux:fedora?logo=github&style=for-the-badge' + :alt: GitHub issues by-label + +#. Download the corresponding `.rpm` file, e.g. ``sunshine-fedora_35.rpm`` +#. ``sudo rpm -i ``, e.g. ``sudo rpm -i ./sunshine-fedora_35.rpm`` + +.. Note:: If this is the first time installing. + + .. code-block:: bash + + sudo usermod -a -G input $USER + sudo reboot now + +.. Tip:: Optionally, run Sunshine in the background. + + .. code-block:: bash + + systemctl --user start sunshine + +MacOS +----- +.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:macos?logo=github&style=for-the-badge' + :alt: GitHub issues by-label + +#. Install `MacPorts `_ +#. Download the `Portfile `_ from this repository to + ``/tmp`` +#. In a terminal run ``cd /tmp && sudo port install`` +#. The first time you start Sunshine, you will be asked to grant access to screen recording and your microphone. + +Windows +------- +.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:windows:10?logo=github&style=for-the-badge' + :alt: GitHub issues by-label + +.. image:: https://img.shields.io/github/issues/sunshinestream/sunshine/os:windows:11?logo=github&style=for-the-badge' + :alt: GitHub issues by-label + +#. Download and extract ``sunshine-windows.zip`` + +.. _latest release: https://github.com/SunshineStream/Sunshine/releases/latest +.. _Dockerhub.io: https://hub.docker.com/repository/docker/sunshinestream/sunshine +.. _ghcr.io: https://github.com/orgs/SunshineStream/packages?repo_name=sunshine diff --git a/docs/source/about/overview.rst b/docs/source/about/overview.rst new file mode 100644 index 00000000..e4a3ad51 --- /dev/null +++ b/docs/source/about/overview.rst @@ -0,0 +1 @@ +.. include:: ../../../README.rst diff --git a/docs/source/about/third_party_packages.rst b/docs/source/about/third_party_packages.rst new file mode 100644 index 00000000..4f349abe --- /dev/null +++ b/docs/source/about/third_party_packages.rst @@ -0,0 +1,65 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/about/third_party_packages.rst + +Third Party Packages +==================== + +.. Warning:: These packages are not maintained by SunshineStream. Use at your own risk. + +AUR (Arch Linux User Repository) +-------------------------------- + +.. image:: https://img.shields.io/aur/version/sunshine?style=for-the-badge&logo=archlinux + :alt: AUR version + +.. image:: https://img.shields.io/aur/last-modified/sunshine?style=for-the-badge&logo=archlinux + :alt: AUR last modified + +.. image:: https://img.shields.io/aur/votes/sunshine?style=for-the-badge&logo=archlinux + :alt: AUR votes + +.. image:: https://img.shields.io/aur/maintainer/sunshine?style=for-the-badge&logo=archlinux + :alt: AUR maintainer + +.. image:: https://img.shields.io/static/v1?label=maintainer&message=hadogenes&color=blue&style=for-the-badge&logo=github + :alt: GitHub Maintainer + :target: https://github.com/hadogenes + +Chocolatey +---------- + +.. image:: https://img.shields.io/chocolatey/v/Sunshine?style=for-the-badge&logo=chocolatey + :alt: Chocolatey Version + +.. image:: https://img.shields.io/chocolatey/dt/sunshine?style=for-the-badge&logo=chocolatey + :alt: Chocolatey + +.. image:: https://img.shields.io/static/v1?label=maintainer&message=AeliusSaionji&color=blue&style=for-the-badge&logo=github + :alt: GitHub Maintainer + :target: https://github.com/AeliusSaionji + +Scoop +----- + +.. image:: https://img.shields.io/scoop/v/sunshine?bucket=extras&style=for-the-badge + :alt: Scoop Version (extras bucket) + +.. image:: https://img.shields.io/static/v1?label=maintainer&message=sitiom&color=blue&style=for-the-badge&logo=github + :alt: GitHub Maintainer + :target: https://github.com/sitiom + + +Legacy GitHub Repo +------------------ + +.. image:: https://img.shields.io/github/last-commit/loki-47-6F-64/sunshine?style=for-the-badge&logo=github + :alt: GitHub last commit + +.. image:: https://img.shields.io/github/release-date/loki-47-6F-64/sunshine?style=for-the-badge&logo=github + :alt: GitHub Release Date + +.. image:: https://img.shields.io/github/downloads/loki-47-6F-64/sunshine/total?style=for-the-badge&logo=github + :alt: GitHub Releases + +.. image:: https://img.shields.io/static/v1?label=maintainer&message=loki-47-6F-64&color=blue&style=for-the-badge&logo=github + :alt: GitHub Maintainer + :target: https://github.com/loki-47-6F-64 diff --git a/docs/source/about/usage.rst b/docs/source/about/usage.rst new file mode 100644 index 00000000..6eafe4b9 --- /dev/null +++ b/docs/source/about/usage.rst @@ -0,0 +1,163 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/about/usage.rst + +Usage +===== +#. See the `setup`_ section for your specific OS. +#. Run ``sunshine /sunshine.conf``. + + .. Note:: The configuration file specified will be created if it doesn't exist. + + .. Tip:: If using the Linux AppImage, replace ``sunshine`` with ``./sunshine.AppImage`` + +#. Configure Sunshine in the web ui + The web ui is available on `https://localhost:47990 `_ by default. You may replace + `localhost` with your internal ip address. + + .. Tip:: Ignore any warning given by your browser about "insecure website". + + .. Caution:: If running for the first time, make sure to note the username and password Sunshine showed to you, + since you cannot get back later! + + Add games and applications. + This can be configured in the web ui. + + .. Note:: Additionally, apps can be configured manually. `assets/apps_.json` is an example of a list of + applications that are started just before running a stream. + + .. Note:: Application list is not fully supported on MacOS + +#. In Moonlight, you may need to add the PC manually. +#. When Moonlight request you insert the correct pin on sunshine: + + - Login to the web ui + - Go to "PIN" in the Header + - Type in your PIN and press Enter, you should get a Success Message + - In Moonlight, select one of the Applications listed + +Network +------- +Sunshine will be available on port 47990 by default. + +.. Warning:: Do not expose port 47990, or the web ui, to the internet! + +Arguments +--------- +To get a list of available arguments run the following: + + .. code-block:: bash + + sunshine --help + +Setup +----- + +Linux +^^^^^ +Sunshine needs access to `uinput` to create mouse and gamepad events. + +Add user to group `input`. + .. code-block:: bash + + usermod -a -G input $USER + +Create `udev` rules. + .. code-block:: bash + + nano /etc/udev/rules.d/85-sunshine-input.rules + + Input the following contents: + ``KERNEL=="uinput", GROUP="input", MODE="0660"`` + + Save the file and exit: + + #. ``CTRL+X`` to start exit. + #. ``Y`` to save modifications. + +Configure autostart service + `path/to/build/dir/sunshine.service` is used to start sunshine in the background. To use it, do the following: + + #. Copy it to the users systemd: ``cp sunshine.service ~/.config/systemd/user/`` + #. Starting + + - One time: ``systemctl --user start sunshine`` + - Always on boot: ``systemctl --user enable sunshine`` + +Additional Setup for KMS + .. 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: ``sudo setcap cap_sys_admin+p sunshine`` + +MacOS +^^^^^ +Sunshine can only access microphones on macOS due to system limitations. To stream system audio use +`Soundflower `_ or +`BlackHole `_ and +select their sink as audio device in `sunshine.conf`. + +.. Note:: Command Keys are not forwarded by Moonlight. Right Option-Key is mapped to CMD-Key. + +.. Caution:: Gamepads are not supported. + +Windows +^^^^^^^ +For gamepad support, install `ViGEmBus `_ + +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/F13`` - Switch to different monitor for Streaming + +Application List +---------------- +- 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 replaced by ``$(HOME)`` +- ``env`` - Adds or overwrites Environment variables for the commands/applications run by Sunshine +- ``"Variable name":"Variable value"`` +- ``apps`` - The list of applications +- Example application: + + .. code-block:: json + + { + "name":"An App", + "cmd":"command to open app", + "prep-cmd":[ + { + "do":"some-command", + "undo":"undo-that-command" + } + ], + "detached":[ + "some-command", + "another-command" + ] + } + + - ``name`` - The name of the application/game + - ``output`` - The file where the output of the command is stored + - ``detached`` - A list of commands to be run and forgotten about + - ``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 + + - This should not fail considering it is supposed to undo the ``do`` commands + - If it fails, Sunshine is terminated + + - ``cmd`` - The main application + + - If not specified, a process is started that sleeps indefinitely + +Considerations +-------------- +- 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. +- In addition to the apps listed, one app "Desktop" is hardcoded into Sunshine. It does not start an application, + instead it simply starts a stream. diff --git a/docs/source/building/build.rst b/docs/source/building/build.rst new file mode 100644 index 00000000..556725fc --- /dev/null +++ b/docs/source/building/build.rst @@ -0,0 +1,31 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/building/build.rst + +Build +===== +Sunshine binaries are built using `CMake `_. Cross compilation is not +supported. That means the binaries must be built on the target operating system and architecture. + +Building Locally +---------------- + +Clone +^^^^^ +Ensure `git `_ is installed and run the following: + + .. code-block:: bash + + git clone https://github.com/sunshinestream/sunshine.git --recurse-submodules + cd sunshine && mkdir build && cd build + +Build +^^^^^ +See the section specific to your OS. + +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 diff --git a/docs/source/building/linux.rst b/docs/source/building/linux.rst new file mode 100644 index 00000000..9f87d588 --- /dev/null +++ b/docs/source/building/linux.rst @@ -0,0 +1,241 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/building/linux.rst + +Linux +===== + +Requirements +------------ +.. Warning:: Installing these dependencies may break your distribution. It is recommended to build in a virtual machine + or to use the Dockerfile builds located in the `./scripts` directory. + +Debian Bullseye +""""""""""""""" +End of Life: TBD + +Install Requirements + .. code-block:: bash + + sudo apt update && sudo apt install \ + build-essential \ + cmake \ + git \ + libavdevice-dev \ + libboost-filesystem-dev \ + libboost-log-dev \ + libboost-thread-dev \ + libcap-dev \ # KMS + libdrm-dev \ # KMS + libevdev-dev \ + libpulse-dev \ + libopus-dev \ + libssl-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 + nvidia-cuda-dev \ # Cuda, NvFBC + nvidia-cuda-toolkit \ # Cuda, NvFBC + +Fedora 35 +""""""""" +End of Life: TBD + +Install Repositories + .. code-block:: bash + + sudo dnf update && \ + sudo dnf group install "Development Tools" && \ + 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 + +Install Requirements + .. code-block:: bash + + sudo dnf install \ + boost-devel \ + boost-static.x86_64 \ + cmake \ + ffmpeg-devel \ + gcc-c++ \ + libevdev-devel \ + libX11-devel \ # X11 + libxcb-devel \ # X11 + libXcursor-devel \ # X11 + libXfixes-devel \ # X11 + libXinerama-devel \ # X11 + libXi-devel \ # X11 + libXrandr-devel \ # X11 + libXtst-devel \ # X11 + mesa-libGL-devel \ + openssl-devel \ + opus-devel \ + pulseaudio-libs-devel \ + rpm-build \ # if you want to build an RPM binary package + +Ubuntu 18.04 +"""""""""""" +End of Life: April 2028 + +Install Repositories + .. code-block:: bash + + sudo apt update && sudo apt install \ + software-properties-common \ + && add-apt-repository ppa:savoury1/graphics && \ + add-apt-repository ppa:savoury1/multimedia && \ + add-apt-repository ppa:savoury1/ffmpeg4 && \ + add-apt-repository ppa:savoury1/boost-defaults-1.71 && \ + add-apt-repository ppa:ubuntu-toolchain-r/test && \ + +Install Requirements + .. code-block:: bash + + sudo apt install \ + build-essential \ + cmake \ + gcc-10 \ + git \ + g++-10 \ + libavdevice-dev \ + libboost-filesystem1.71-dev \ + libboost-log1.71-dev \ + libboost-regex1.71-dev \ + libboost-thread1.71-dev \ + libcap-dev \ # KMS + libdrm-dev \ # KMS + libevdev-dev \ + libpulse-dev \ + libopus-dev \ + libssl-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 + wget \ + +Update gcc alias + .. code-block:: bash + + update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100 --slave /usr/bin/g++ g++ /usr/bin/g++-10 + +Install CuDA + .. code-block:: bash + + wget https://developer.download.nvidia.com/compute/cuda/11.4.2/local_installers/cuda_11.4.2_470.57.02_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 + +Install CMake + .. code-block:: bash + + wget https://cmake.org/files/v3.22/cmake-3.22.2-linux-x86_64.sh + mkdir /opt/cmake + sh /cmake-3.22.2-linux-x86_64.sh --prefix=/opt/cmake --skip-license + ln -s /opt/cmake/bin/cmake /usr/local/bin/cmake + cmake --version + +Ubuntu 20.04 +"""""""""""" +End of Life: April 2030 + +Install Requirements + .. code-block:: bash + + sudo apt update && sudo apt install \ + build-essential \ + cmake \ + git \ + g++-10 \ + libavdevice-dev \ + libboost-filesystem-dev \ + libboost-log-dev \ + libboost-thread-dev \ + libcap-dev \ # KMS + libdrm-dev \ # KMS + libevdev-dev \ + libpulse-dev \ + libopus-dev \ + libssl-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 + wget \ + +Update gcc alias + .. code-block:: bash + + update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100 --slave /usr/bin/g++ g++ /usr/bin/g++-10 + +Install CuDA + .. code-block:: bash + + wget https://developer.download.nvidia.com/compute/cuda/11.4.2/local_installers/cuda_11.4.2_470.57.02_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 + +Ubuntu 21.10 +"""""""""""" +End of Life: July 2022 + +Install Requirements + .. code-block:: bash + + sudo apt update && sudo apt install \ + build-essential \ + cmake \ + git \ + libavdevice-dev \ + libboost-filesystem-dev \ + libboost-log-dev \ + libboost-thread-dev \ + libcap-dev \ # KMS + libdrm-dev \ # KMS + libevdev-dev \ + libpulse-dev \ + libopus-dev \ + libssl-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 + nvidia-cuda-dev \ # Cuda, NvFBC + nvidia-cuda-toolkit \ # Cuda, NvFBC + +Ubuntu 22.04 +"""""""""""" +End of Life: April 2027 + +.. Todo:: Create Ubuntu 22.04 Dockerfile and complete this documentation. + +Build +----- +.. Caution:: Ensure you are in the build directory created during the clone step earlier before continuing. + +Debian based OSes + .. code-block:: bash + + cmake -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_CXX_COMPILER=g++-10 .. + +Red Hat based Oses + .. code-block:: bash + + cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ .. + +Finally + .. code-block:: bash + + make -j ${nproc} diff --git a/docs/source/building/macos.rst b/docs/source/building/macos.rst new file mode 100644 index 00000000..c763ad12 --- /dev/null +++ b/docs/source/building/macos.rst @@ -0,0 +1,41 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/building/macos.rst + +MacOS +===== + +Requirements +------------ +MacOS Big Sur and Xcode 12.5+ + +Use either `MacPorts `_ or `Homebrew `_ + +MacPorts +"""""""" +Install Requirements + .. code-block:: bash + + sudo port install cmake boost libopus ffmpeg + +Homebrew +"""""""" +Install Requirements + .. code-block:: bash + + brew install boost cmake ffmpeg libopusenc + # if there are issues with an SSL header that is not found: + cd /usr/local/include + ln -s ../opt/openssl/include/openssl . + +Build +----- +.. Caution:: Ensure you are in the build directory created during the clone step earlier before continuing. + + .. code-block:: bash + + cmake .. + make -j ${nproc} + +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.76 ..`` + diff --git a/docs/source/building/windows.rst b/docs/source/building/windows.rst new file mode 100644 index 00000000..6a7c1e16 --- /dev/null +++ b/docs/source/building/windows.rst @@ -0,0 +1,22 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/building/windows.rst + +Windows +======= + +Requirements +------------ +First you need to install `MSYS2 `_, then startup "MSYS2 MinGW 64-bit" and install the +following packages using: + +.. code-block:: batch + + pacman -S mingw-w64-x86_64-binutils mingw-w64-x86_64-openssl mingw-w64-x86_64-cmake mingw-w64-x86_64-toolchain mingw-w64-x86_64-opus mingw-w64-x86_64-x265 mingw-w64-x86_64-boost git mingw-w64-x86_64-make cmake make gcc + +Build +----- +.. Caution:: Ensure you are in the build directory created during the clone step earlier before continuing. + + .. code-block:: batch + + cmake -G"Unix Makefiles" .. + mingw32-make diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..0375d42b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,88 @@ +# 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 + + +# -- 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. +import os +# import sys + +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' +copyright = f'{datetime.now ().year}, {project}' +author = 'ReenigneArcher' + +# The full version, including alpha/beta/rc tags +# version = '0.13.0' + + +# -- 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 +] + +# 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 ------------------------------------------------- + +# 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'] + +html_logo = os.path.join(root_dir, 'sunshine.ico') + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' + +html_theme_options = { + # 'analytics_id': 'G-XXXXXXXXXX', # Provided by Google in your dashboard + # 'analytics_anonymize_ip': False, + 'logo_only': False, + 'display_version': False, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': True, + 'vcs_pageview_mode': 'blob', + # 'style_nav_header_background': 'white', + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False, +} + +# extension config options +autosectionlabel_prefix_document = True # Make sure the target is unique +todo_include_todos = True diff --git a/docs/source/contributing/contributing.rst b/docs/source/contributing/contributing.rst new file mode 100644 index 00000000..d9f5106f --- /dev/null +++ b/docs/source/contributing/contributing.rst @@ -0,0 +1,32 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/contributing/contributing.rst + +Contributing +============ +#. Fork the repo on GitHub +#. Create a new branch for the feature you are adding or the issue you are fixing + + .. Tip:: Base the new branch off the `nightly` branch. It will make your life easier when you submit the PR! + +#. Make changes, push commits, etc. +#. Files should contain an empty line at the end. +#. Document your code! +#. Test your code! +#. When ready create a PR to this repo on the `nightly` branch. + + .. Hint:: If you accidentally make your PR against a different branch, a bot will comment letting you know it's on + the wrong branch. Don't worry. You can edit the PR to change the target branch. There is no reason to close the + PR! + + .. Note:: Draft PRs are also welcome as you work through issues. The benefit of creating a draft PR is that an + automated build can run in a github runner. + + .. Attention:: Do not expect partially complete PRs to be merged. These topics will be considered before merging. + + - Does the code follows the style guidelines of this project? + + .. Tip:: Look at examples of existing code in the project! + + - Is the code well commented? + - Were documentation blocks updated for new or modified components? + + .. Note:: Developers and maintainers will attempt to assist with challenging issues. diff --git a/docs/source/contributing/localization.rst b/docs/source/contributing/localization.rst new file mode 100644 index 00000000..6d0f6556 --- /dev/null +++ b/docs/source/contributing/localization.rst @@ -0,0 +1,80 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/contributing/localization.rst + +Localization +============ +Sunshine is being localized into various languages. The default language is `en` (English) and is highlighted green. + +.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=de&style=for-the-badge&query=%24.progress.0.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json +.. image:: https://img.shields.io/badge/dynamic/json?color=green&label=en&style=for-the-badge&query=%24.progress.1.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json +.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=en-GB&style=for-the-badge&query=%24.progress.2.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json +.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=en-US&style=for-the-badge&query=%24.progress.3.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json +.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=es-ES&style=for-the-badge&query=%24.progress.4.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json +.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=fr&style=for-the-badge&query=%24.progress.5.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json +.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=it&style=for-the-badge&query=%24.progress.6.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json +.. image:: https://img.shields.io/badge/dynamic/json?color=blue&label=ru&style=for-the-badge&query=%24.progress.7.data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503956.json + +Graph + .. image:: https://badges.awesome-crowdin.com/translation-15178612-503956.png + +CrowdIn +------- +The translations occur on +`CrowdIn `_. Feel free to contribute to localization there. +Only elements of the API are planned to be translated. + +.. Note:: The rest API has not yet been implemented. + +Translations Basics + - The brand names `SunshineStream` 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_nightly` branch and a PR is made against the + `nightly` branch. Once PR is merged, all updated translations are part of the project and will be included in the + next release. + +Extraction +---------- +There should be minimal cases where strings need to be extracted from source code; however it may be necessary in some +situations. For example if a system tray icon is added it should be localized as it is user interfacing. + + - Wrap the string to be extracted in a function as shown. + + .. code-block:: cpp + + #include + boost::locale::translate("Hello world!") + +.. 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 `nightly` branch. Jobs are only run if +any of the following paths are modified. + + .. code-block:: yaml + + - 'sunshine/**' + +When testing locally it may be desirable to manually extract, initialize, update, and compile strings. Python is +required for this, along with the dependencies in the `./scripts/requirements.txt` file. + + Extract, initialize, and update + .. code-block:: bash + + python ./scripts/_locale.py --extract --init --update + + Compile + .. code-block:: bash + + python ./scripts/_locale.py --compile diff --git a/docs/source/contributing/testing.rst b/docs/source/contributing/testing.rst new file mode 100644 index 00000000..a08c6f9c --- /dev/null +++ b/docs/source/contributing/testing.rst @@ -0,0 +1,42 @@ +:github_url: https://github.com/RetroArcher/RetroArcher/tree/nightly/docs/source/contributing/testing.rst + +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/clang.yml`. + +Test clang-format locally. + .. Todo:: This documentation needs to be improved. + + .. code-block:: bash + + clang-format ... + +Sphinx +------ +Sunshine uses `Sphinx `_ for documentation building. Sphinx is included +in the `./scripts/requirements.txt` file. Python is required to build sphinx docs. Installation and setup of python +will not be covered here. + +The config file for Sphinx is `docs/source/conf.py`. 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 + +Unit Testing +------------ +.. Todo:: Sunshine does not currently have any unit tests. If you would like to help us improve please get in contact + with us, or make a PR with suggested changes. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..5384c8e2 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,7 @@ +:github_url: https://github.com/SunshineStream/Sunshine/tree/nightly/docs/source/index.rst + +SunshineStream has this documentation hosted on `Read the Docs `_. + +Table of Contents +================= +.. include:: toc.rst diff --git a/docs/source/toc.rst b/docs/source/toc.rst new file mode 100644 index 00000000..9c0989ee --- /dev/null +++ b/docs/source/toc.rst @@ -0,0 +1,27 @@ +.. toctree:: + :maxdepth: 2 + :caption: About + + about/overview + about/installation + about/docker + about/third_party_packages + about/usage + about/advanced_usage + +.. toctree:: + :maxdepth: 2 + :caption: Build + + building/build + building/linux + building/macos + building/windows + +.. toctree:: + :maxdepth: 2 + :caption: Contributing + + contributing/contributing + contributing/localization + contributing/testing diff --git a/scripts/Dockerfile-debian b/scripts/Dockerfile-debian index 3a53fd9f..fc77eb8e 100644 --- a/scripts/Dockerfile-debian +++ b/scripts/Dockerfile-debian @@ -1,5 +1,7 @@ FROM debian:bullseye AS sunshine-debian +# Debian Bullseye end of life is TBD + ARG DEBIAN_FRONTEND=noninteractive ARG TZ="Europe/London" @@ -11,9 +13,9 @@ RUN apt-get update -y && \ cmake \ git \ libavdevice-dev \ - libboost-thread-dev \ libboost-filesystem-dev \ libboost-log-dev \ + libboost-thread-dev \ libcap-dev \ libdrm-dev \ libevdev-dev \ diff --git a/scripts/Dockerfile-fedora_33 b/scripts/Dockerfile-fedora_33 index 50a4e3db..136058c3 100644 --- a/scripts/Dockerfile-fedora_33 +++ b/scripts/Dockerfile-fedora_33 @@ -1,5 +1,8 @@ FROM fedora:33 AS sunshine-fedora_33 +# Fedora 33 end of life is November 2021 +# This file remains for reference only + SHELL ["/bin/bash", "-o", "pipefail", "-c"] RUN dnf -y update && \ dnf -y group install "Development Tools" && \ diff --git a/scripts/Dockerfile-fedora_35 b/scripts/Dockerfile-fedora_35 index d4f5d843..18b04377 100644 --- a/scripts/Dockerfile-fedora_35 +++ b/scripts/Dockerfile-fedora_35 @@ -1,5 +1,7 @@ FROM fedora:35 AS sunshine-fedora_35 +# Fedora 35 end of life is TBD + SHELL ["/bin/bash", "-o", "pipefail", "-c"] RUN dnf -y update && \ dnf -y group install "Development Tools" && \ @@ -11,8 +13,8 @@ RUN dnf -y update && \ ffmpeg-devel \ gcc-c++ \ libevdev-devel \ - libxcb-devel \ libX11-devel \ + libxcb-devel \ libXcursor-devel \ libXfixes-devel \ libXinerama-devel \ diff --git a/scripts/Dockerfile-ubuntu_18_04 b/scripts/Dockerfile-ubuntu_18_04 index 7225c0c7..6ad3e8c0 100644 --- a/scripts/Dockerfile-ubuntu_18_04 +++ b/scripts/Dockerfile-ubuntu_18_04 @@ -1,5 +1,7 @@ FROM ubuntu:18.04 AS sunshine-ubuntu_18_04 +# Ubuntu 18.04 end of life is April 2028 + ARG DEBIAN_FRONTEND=noninteractive ARG TZ="Europe/London" diff --git a/scripts/Dockerfile-ubuntu_20_04 b/scripts/Dockerfile-ubuntu_20_04 index 9ae7dfa9..44e897a7 100644 --- a/scripts/Dockerfile-ubuntu_20_04 +++ b/scripts/Dockerfile-ubuntu_20_04 @@ -1,5 +1,7 @@ FROM ubuntu:20.04 AS sunshine-ubuntu_20_04 +# Ubuntu 20.04 end of life is April 2030 + ARG DEBIAN_FRONTEND=noninteractive ARG TZ="Europe/London" diff --git a/scripts/Dockerfile-ubuntu_21_04 b/scripts/Dockerfile-ubuntu_21_04 index 00801c55..012845a5 100644 --- a/scripts/Dockerfile-ubuntu_21_04 +++ b/scripts/Dockerfile-ubuntu_21_04 @@ -1,5 +1,8 @@ FROM ubuntu:21.04 AS sunshine-ubuntu_21_04 +# Ubuntu 21.04 end of life is January 2022 +# This file remains for reference only + ARG DEBIAN_FRONTEND=noninteractive ARG TZ="Europe/London" diff --git a/scripts/Dockerfile-ubuntu_21_10 b/scripts/Dockerfile-ubuntu_21_10 index 83b3e7f8..6be49dbe 100644 --- a/scripts/Dockerfile-ubuntu_21_10 +++ b/scripts/Dockerfile-ubuntu_21_10 @@ -1,5 +1,7 @@ FROM ubuntu:21.10 AS sunshine-ubuntu_21_10 +# Ubuntu 21.10 end of life is July 2022 + ARG DEBIAN_FRONTEND=noninteractive ARG TZ="Europe/London" @@ -10,9 +12,9 @@ RUN apt-get update -y && \ cmake \ git \ libavdevice-dev \ - libboost-thread-dev \ libboost-filesystem-dev \ libboost-log-dev \ + libboost-thread-dev \ libcap-dev \ libdrm-dev \ libevdev-dev \ diff --git a/scripts/_locale.py b/scripts/_locale.py index 82e172cc..e47887cc 100644 --- a/scripts/_locale.py +++ b/scripts/_locale.py @@ -1,4 +1,6 @@ -"""_locale.py +""" +.. + _locale.py Functions related to building, initializing, updating, and compiling localization translations. @@ -62,7 +64,7 @@ def x_extract(): commands.append(filename) print(commands) - proc = subprocess.run(args=commands, cwd=root_dir) + subprocess.check_output(args=commands, cwd=root_dir) # fix header body = "" @@ -98,7 +100,7 @@ def babel_init(locale_code: str): ] print(commands) - proc = subprocess.run(args=commands, cwd=root_dir) + subprocess.check_output(args=commands, cwd=root_dir) def babel_update(): @@ -113,7 +115,7 @@ def babel_update(): ] print(commands) - proc = subprocess.run(args=commands, cwd=root_dir) + subprocess.check_output(args=commands, cwd=root_dir) def babel_compile(): @@ -126,13 +128,13 @@ def babel_compile(): ] print(commands) - proc = subprocess.run(args=commands, cwd=root_dir) + subprocess.check_output(args=commands, cwd=root_dir) if __name__ == '__main__': # Set up and gather command line arguments parser = argparse.ArgumentParser( - description='Script helps update locale_id translations. Translations must be done manually.') + description='Script helps update locale translations. Translations must be done manually.') parser.add_argument('--extract', action='store_true', help='Extract messages from c++ files.') parser.add_argument('--init', action='store_true', help='Initialize any new locales specified in target locales.') diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 9d236e72..c089efd9 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -1 +1,4 @@ Babel==2.9.1 +m2r2==0.3.2 +Sphinx==4.5.0 +sphinx-rtd-theme==1.0.0