Sunshine/docs/source/about/usage.rst

Usage
=====
#. See the `setup`_ section for your specific OS.
#. Run ``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.

   .. 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 <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".

   .. 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. `src_assets/<os>/config/apps.json` is an example of a
            list of applications that are started just before running a stream. This is the directory within the GitHub
            repo.

         .. Attention:: 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 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:
   .. code-block:: bash

      sunshine --help

Setup
-----

Linux
^^^^^
The `deb`, `rpm`, and `AppImage` packages handle these steps automatically. The flatpak does not, third party packages
also may not.

Sunshine needs access to `uinput` to create mouse and gamepad events.

#. Add user to group `input`, if this is the first time installing.
      .. code-block:: bash

         sudo usermod -a -G input $USER

#. Create `udev` rules.
      .. code-block::

         echo 'KERNEL=="uinput", GROUP="input", MODE="0660", OPTIONS+="static_node=uinput"' | \
         sudo tee /etc/udev/rules.d/85-sunshine-input.rules

#. Optionally, configure autostart service

   - filename: ``~/.config/systemd/user/sunshine.service``
   - contents:
         .. code-block::

            [Unit]
            Description=Sunshine Gamestream Server for Moonlight

            [Service]
            ExecStart=<see table>

            [Install]
            WantedBy=graphical-session.target

         .. table::
            :widths: auto

            ========   ==============================================   ===============
            package    ExecStart                                        Auto Configured
            ========   ==============================================   ===============
            aur        /usr/bin/sunshine                                ✔
            deb        /usr/bin/sunshine                                ✔
            rpm        /usr/bin/sunshine                                ✔
            AppImage   ~/sunshine.AppImage                              ✔
            Flatpak    flatpak run dev.lizardbyte.sunshine              ✖
            ========   ==============================================   ===============

   **Start once**
         .. code-block:: bash

            systemctl --user start sunshine

   **Start on boot**
         .. code-block:: bash

            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.

      **Enable**
         .. code-block:: bash

            sudo setcap cap_sys_admin+p $(readlink -f $(which sunshine))

      **Disable**
         .. code-block:: bash

            sudo setcap -r $(readlink -f $(which sunshine))

#. Reboot
      .. code-block:: bash

         sudo reboot now

macOS
^^^^^
Sunshine can only access microphones on macOS due to system limitations. To stream system audio use
`Soundflower <https://github.com/mattingalls/Soundflower>`_ or
`BlackHole <https://github.com/ExistentialAudio/BlackHole>`_ 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 currently supported.

Configure autostart service
   **MacPorts**
      .. code-block:: bash

         sudo port load Sunshine

Windows
^^^^^^^
For gamepad support, install `ViGEmBus <https://github.com/ViGEm/ViGEmBus/releases/latest>`_

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
----------------
- Applications should be configured via the web UI.
- A basic understanding of working directories and commands is recommended.
- 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
- 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.

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

- 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.
- For the Linux flatpak you must prepend commands with ``flatpak-spawn --host``.