Watcherstream

This section explains more in-depth configuration of watcherstream. For installation and basic usage, see Getting Started.

The srtg-watcherstream can operate in multiple modes, depending on the users’ needs. Following modes are supported:

  • default

  • obs

  • rtsp

The mode can be selected by adding watcherstream_mode = <mode> to the top-level of /etc/srtg/srtg.toml

Default mode

The default mode uploads the player view as-is to Surrogate.tv.

OBS mode

Setup

If you want to customize your stream further, obs mode can be used. In this mode, the srtg-watcherstream does not generate the stream but instead only uploads a stream generated by OBS. For example, if you have a separate PC which you would like to use to modify the watcherstream, this mode can be utilized for streaming to surrogate.tv.

The srtg-watcherstream does not need any other configuration except the aforementioned watcherstream_mode. After changing the mode, run sudo systemctl restart srtg to reload the configuration.

OBS needs to be configured to record the stream in HLS format to a specific location. To do so,

  1. Go to settings->Output in OBS

  2. Set Recording Format to m3u8 or HLS (only one of these should be in the dropdown list)

  3. Set Recording Path to /tmp/srtg_hls

    obs-conf-1
  4. Go to settings->Advanced

  5. Set Filename Formatting under Recording to main

  6. Turn on Overwrite if file exists under the filename formatting option

obs-conf-2

After these steps, click Start recording and the stream should soon appear in your game’s page. If there is need to stream to some other service than Surrogate.tv at the same time, OBS supports recording and streaming simultaneously. In that case, setup streaming settings for whichever service you are using according to their instructions.

Scene switching

OBS setup

OBS scene switching is supported using OBS’s Advanced Scene Switcher. The switching works based on contents of a file, and a python script can be used to write the file contents and trigger a scene switch.

To setup scene switching, first install the Advanced Scene Switcher plugin according to the instructions.

To setup your Advanced Scene Switcher,

  1. Open Advanced Scene Switcher settings from tools->Advanced Scene Switcer

  2. Go to File tab in the settings

  3. Check the “Enable switching of scenes based on file input”

  4. Enter a file to the “Read scene name to be switched to from this file”. Take a note which file you are using, as you need to input the same file to the python script which writes to it.

obs-scene-1

Python setup

The python class for writing scene files can be found in utils/obs_scene_switcher.py. If you are running controller and OBS on the same machine, you can include OBSSceneSwitcher in your controller implementation. The scene switcher is very simple: you initialize the class with the same path that you entered to OBS. After that you can call change_scene with the scene name you want to activate.

If you are running OBS on a separate machine or you do not want to modify controller code, you can run the scene switcher in a standalone mode. See the bottom of obs_scene_switcher.py for an example.

RTSP mode

The RTSP mode can be used when the watcherstream is needed on another machine, e.g. if you are running multiple Raspberry Pi based robots and want to create a sophisticated watcher experience that aggregates streams from multiple robots.

The srtg-watcherstream does not need any other configuration except setting watcherstream_mode to rtsp. After changing the mode, run sudo systemctl restart srtg to reload the configuration.

First, you need to setup OBS. To get the stream as an input into an OBS scene, do the following

  1. Check the Raspi’s local IP from admin panel

    1. Go to your game’s settings page

    2. Select Game Engine tab

    3. Scroll down to the correct robot and copy the IP address from Local Config URL

  2. Add a new VLC Video Source.

  3. Click the + sign on the right and select Add Path/URL.

  4. Add the following URL: rtsp://<local_ip_from_step_1>:8554/unicast

obs-rtsp-conf

Then you need to setup the stream uploading. The steps for this depend on your platform

Linux

On a (Debian based, e.g. Ubuntu, Mint, Debian) Linux, install srtg-watcherstream by running sudo apt install srtg-watcherstream. Refer to OBS mode on the setup.

Windows

On a Windows 10 machine, first install Windows Subsystem for Linux 2. Run a Ubuntu 20.04 virtual machine in WSL2 according to the instructions. Once you have an Ubuntu VM running, install watcherstream package. Following commands need to be run:

sudo sh -c 'echo deb https://apt.surrogate.tv/ buster main >> /etc/apt/sources.list'

sudo apt-key adv --keyserver "hkps://keys.openpgp.org" --recv-keys "58278AC826D269F82F1AD74AD7337870E6E07980"

sudo apt-get update

sudo apt install srtg-watcherstream

The setup steps for the stream itself are almost same as in OBS section. Following extra steps need to be done:

  1. Create config directory by running sudo mkdir /etc/srtg

  2. Create a config file with your choice of editor, e.g. sudo nano /etc/srtg/srtg.toml

  3. Add watcherstream_mode = obs to the config file.

  4. Add a game engine section to the config file

    [game_engine]
    url = "https://ge.surrogate.tv/signaling"
    token = "<token from your admin panel>"
    
  5. In the OBS settings, instead of setting Recording Path according to OBS instructions, set it to the path pointing to the WSL2. The path should be \\wsl$\Ubuntu-20.04\tmp\srtg_hls.

If this path does not work for some reason, open a file explorer in Windows. Type \\wsl$ to the address bar and open the directory of the virtual machine. Find directory tmp and open it. Finally, open directory srtg_hls and copy the address found on the address bar and enter this path to OBS.

After that, because WSL2 machines do not use systemd, you need to manually run the watcherstream program. To do so, run sudo python3 /usr/bin/srtg-watcherstream. Note that this does not run the program as a service and you have to re-run it always when you reboot your computer or when there is an error.

Games with multiple robots

In case your game consists of multiple robots, only one of them can stream the watcherstream. At this point, there’s nothing that prevents multiple robots streaming simultaneously, which breaks the watcherstream. To avoid that, watcherstream needs to be disabled on every robot except one.

To disable the watcherstream, run sudo systemctl --now disable srtg-watcherstream. That command both stops the watcherstreamer and prevents it from starting on the next boot. If you need to re-enable it later, run sudo systemctl --now enable srtg-watcherstream.