RealtimeIRL React-based overlay

This overlay is designed to be used in OBS in conjunction with the RealtimeIRL app.

Getting started

Caution

Existing users:
This app has been completely rewritten. Please read the documentation thoroughly.

Backup your .env.local file, delete your old copy of the app, then clone the repository again.

Please take note of the new prefixes required in the .env.local file as described below, as well as the new URL parameters and ports, and update your browser source in OBS accordingly.

Requirements

• Mapbox account and API key, which you can create here: https://www.mapbox.com/
• OpenWeatherMap account and API key, which you can create here: https://openweathermap.org/
• RealtimeIRL account and pull key, which you can create here: https://rtirl.com/
• TimezoneDB account and API key, which you can create here: https://timezonedb.com/

Optional:

• StreamElements account and API key, which you can create here: https://streamelements.com/

Installation:

Git must be installed to clone the repository

From a terminal, run the following commands:

git clone https://github.com/scallensc/react-realtimeirl.git
cd react-realtimeirl

A .env.local file is required in the root of the project folder.
You can copy the .env.example file to .env.local and edit the values as required.

Required entries:

VITE_MAPBOX_KEY = INSERTMAPBOXAPIKEYHERE
VITE_OPENWEATHER_KEY = INSERTOPENWEATHERMAPAPIKEYHERE
VITE_PULL_KEY = INSERTREALTIMEIRLPULLKEYHERE
VITE_TIMEZONE_KEY = INSERTTIMEZONEDBAPIKEYHERE

Optional entries:

VITE_STREAMELEMENTS_KEY = INSERTSTREAMELEMENTSAPIKEYHERE

Easiest option - Docker:

You will need to install and configure Docker.

Warning

Ensure you have created the .env.local file as described above, before proceeding. You can copy the .env.example file to .env.local and edit the values as required.

Once Docker Desktop has been installed and the engine is running, from a terminal in the project root folder, you can build the image with the following command:

docker build -t react-realtimeirl .

You should see the following output:

Now, you can run the image with the following command:

docker run --name react-realtimeirl -p 80:80 -d react-realtimeirl

You should see the following output: (the container ID will be different for you)

Please see the docker documentation for more information on how to use docker, starting/stopping, how to prune containers, etc.

The overlay will now be running at http://localhost

OBS

Add a browser source
Set the URL http://localhost
Set the Width to 1920
Set the Height to 1080

All other settings should be left at default, but please ensure that both these values are unchecked:
☐ Shutdown source when not visible
☐ Refresh browser when scene becomes active

If you followed all of the instructions correctly up to this point, you should now see the overlay in OBS, start pushing data to the RealtimeIRL app, and you should see the overlay updating in real time.

Done!

Self hosting option - Node:

You will need to install NodeJS (v18), as well as Yarn.

After cloning the repository, you will need to install the dependencies, from a terminal in the project root folder, run the following command:

yarn

Note

Ensure you have created the .env.local file as described above, before proceeding. You can copy the .env.example file to .env.local and edit the values as required.

To start the app, run the following command:

yarn start

The overlay will now be running at http://localhost:5173

Follow the above instructions to add the overlay to OBS, ensuring that :5173 is added to the end of the URL in the browser source.

Warning

Existing users:
Bundler changed from CRA to Vite, browser source URL changes from http://localhost:3000 to http://localhost:5173

---

Overlay Control via Chat Commands

This project now includes chat commands that can be used by approved moderators to update and control the overlay. These commands allow moderators to adjust various metrics and settings directly from the chat.

Chat Commands

The following commands can be used to interact with the overlay:

Moderator Management

• Add a Moderator

  • Command: !cycleMod <username>
  • Example: !cycleMod toto

• Remove a Moderator

  • Command: !cycleUnmod <username>
  • Example: !cycleUnmod toto

Distance Tracking

• Add Distance

  • Command: !cycleAdd <target> <value>
  • Example: !cycleAdd totalDistance 2.5

• Subtract Distance

  • Command: !cycleMinus <target> <value>
  • Example: !cycleMinus totalDistance 1.0

• Update Rate

  • Command: !cycleUpdateRatio <tip or sub> <value>
  • Example: !cycleUpdateRatio tip 0.1

Tracking Control

• Pause Tracking

  • Command: !cyclePause

• Unpause Tracking

  • Command: !cycleUnpause

• Reset Current Session

  • Command: !cycleRestartSession

Map Visibility

• Hide Map

  • Command: !cycleHideMap

• Show Map

  • Command: !cycleShowMap

Targets

The following targets can be specified with distance-related commands:

• goalDistance: The goal distance to be reached.
• totalDistance: The total distance covered.
• sessionDistance: The distance covered in the current session.

Usage

Moderators can type the commands directly in the chat to execute the corresponding actions. Only approved moderators have the ability to use these commands.

Examples:

• Adding 2.5 to the total distance: !cycleAdd totalDistance 2.5
• Pausing the tracking: !cyclePause
• Adding a new moderator: !cycleMod toto
• Hiding the map from the overlay: !cycleHideMap

---

This README.md now includes clear instructions on how to use the new chat commands to interact with the overlay.

Customisation

URL parameters can be used for basic customisation of the output of the overlay. For more advanced customisation, you will need to edit the source code.
Each component has a .scss file in the src/components folder, which you can edit to change the appearance of each part of the overlay.

URL parameters:

To enable or disable display of various elements of the overlay, you can use URL parameters, these are described below. Add these to the end of the URL in your browser source in OBS.

Docker e.g:
http://localhost/?theme=mapbox-japan&showMetrics=1&showHeartrate=1&showHeading=1&showAltitude=1&showDistance=1&showSpeed=1

Node e.g:
http://localhost:5173/?theme=mapbox-japan&showMetrics=1&showHeartrate=1&showHeading=1&showAltitude=1&showDistance=1&showSpeed=1

Note

The first parameter must be preceded by ?, and all subsequent parameters must be preceded by &

These parameters are only required if you wish to customise the default output.

Warning

Existing users:
All flags have been changed and no longer need values unless specified below.
e.g.:
disableAnimation=1 becomes disableAnimation
mapZoom still requires a value: mapZoom=15

Animation:

• disableAnimation - disable the animation in/out of the location/weather <> streamelements data container
  disableAnimation

Date/Time:

• hideTime - hide the time
  hideTime

• splitDateTime - split the date and time into separate lines
  splitDateTime

• timeAtBottom - move the date/time display below the map (looks bad with metrics enabled, might be good without)
  timeAtBottom

Map:

• hideMap - hide the map
  hideMap

• mapFollowsHeading - map display will rotate according to heading, instead of being fixed north
  mapFollowsHeading

• mapHasBorder - add a border around the map
  mapHasBorder

• mapIs3d - change to 3D map display
  mapIs3d

• mapIsCircular - make the map circular instead of square
  mapIsCircular

• pulseMarker - enable the pulse animation on the marker
  pulseMarker

• theme - choose from available map themes (default is mapbox-streets - see bottom of this page for more info)
  theme=mapbox-streets

• zoom - set the zoom level of the map (default is 14)
  zoom=14

• zoomLevels - specify zoom level/interval pairs to dynamically adjust map zoom
  zoomLevels=5-5,10-1,15-1

  • This example sets zoom level 5 for 5 minutes, then zoom level 10 for 1 minute, then zoom level 15 for 1 minute, then repeats

Metrics:

• showMetrics - enable metrics container (see below for options) showMetrics

• useImperial - use imperial units instead of metric
  useImperial

Metrics container options:

• showAltitude - enable altitude
  showAltitude

• showDistance - enable total distance
  showDistance

• showHeading - enable heading
  showHeading

• showHeartrate - enable heartrate
  showHeartrate

• showSpeed - enable speed
  showSpeed

Neighbourhood:

• shortLocation - use short location name instead of full info with POI, etc.
  shortLocation

Map themes:

Leaflet based map has been removed and replaced with Mapbox, which has a number of themes available.

All default styles from https://docs.mapbox.com/api/maps/styles/ are available:

theme=mapbox-dark

theme=mapbox-japan

theme=mapbox-light

theme=mapbox-navigation-day

theme=mapbox-navigation-night

theme=mapbox-outdoors

theme=mapbox-satellite

theme=mapbox-satellite-streets

theme=mapbox-streets

Additionally, the following themes from https://www.mapbox.com/gallery are available:

theme=basic

theme=basic-overcast

theme=blueprint

theme=frank

theme=minimo

theme=standard-oil

theme=unicorn

Marvel themes from https://www.mapbox.jp/gallery are also available:

theme=marvel-americachaves

theme=marvel-blackwidow

theme=marvel-blackpanther

theme=marvel-captainamerica

theme=marvel-drstrange

theme=marvel-hulk

theme=marvel-ironman

theme=marvel-thanos

theme=marvel-wanda

Custom themes can be created at https://studio.mapbox.com/

You can then either add an entry to the themes object in src/handlers/handleTheme.ts, and pass the name of this entry as a URL parameter, or you can hardcode the value in src/components/Map.tsx in the style property here:

const map = new mapboxgl.Map({
  style: 'insert mapbox style url here, e.g. mapbox://styles/mapbox/dark-v11',
  center: [location.longitude, location.latitude],
  zoom: parseInt(mapZoom),
  pitch: mapIs3d ? 45 : 0,
  bearing: heading,
  container: mapContainer.current,
  antialias: true
});

Example output with theme=mapbox-dark, metrics options and mapIs3d enabled: