RTIRL Maps Widget

🇬🇧 English (below) · 🇩🇪 Deutsch

A round, toggleable map widget for stream overlays that shows your live location via RealtimeIRL and is controlled through Twitch chat commands (moderators & streamer). Pure static site — hostable as a GitHub Page, embeddable as an OBS/overlay browser source.

Embedding

Use the hosted URL with parameters as a browser source (OBS or similar):

https://elricco.github.io/rtirl-maps-widget/?pullKey=YOUR_PULLKEY&channel=YOUR_CHANNEL

You'll find the Pull Key in your RTIRL settings.

URL parameters

Param	Required	Default	Meaning
pullKey	✅	—	RTIRL pull key
channel	✅	—	Twitch channel (for chat commands)
cmd	✗	!map	Command keyword
pin	✗	Default	URL to a custom marker image
zoom	✗	16	Initial zoom (1–19)
size	✗	250	Widget diameter in px
show	✗	0	1 = start visible on load
border	✗	ffffff	Border color as hex, with or without # (e.g. e8352e, %23000)
borderWidth	✗	4	Border thickness in px, 0 = no border
debug	✗	0	1 = logs config, incoming positions and chat commands to the browser console (DevTools)
speed	✗	0	1 = km/h display enabled on load (like show)
speedFont	✗	Arial	Google Font name for the km/h display (case-insensitive, e.g. Bangers)
speedSize	✗	28	Font size of the km/h display in px (8–200)

Note on speedFont

The name is auto-normalized to Title Case (BANGERS, bangers and Bangers all work). Fonts with unusual casing (e.g. PT Sans, EB Garamond) must be written exactly as on Google Fonts. Use each parameter only once in the URL — with a duplicate speedFont, the first value wins.

Note on the pin URL

A plain image link can be appended directly — : and / do not need escaping:

?pin=https://example.com/mypin.png

If the link itself contains a query string or special characters (&, +, #), it must be percent-encoded once as a whole, otherwise the & truncates the URL or + turns into a space. In the browser console: encodeURIComponent("https://example.com/pin.png?v=2&token=abc")

?pin=https%3A%2F%2Fexample.com%2Fpin.png%3Fv%3D2%26token%3Dabc

Chat commands (broadcaster & moderators only)

Command	Effect
!map on	Show the map
!map off	Hide the map
!map off 30	Hide, automatically show again after 30 s
!map zoom 15	Set zoom (1 = far away, 19 = closest)
!map follow	Map follows the live position (default)
!map freeze	Freeze the position
!map trail on	Show the current session's route as a line
!map trail off	Hide the route
!map speed on	Show speed in km/h below the map
!map speed off	Hide the km/h display
!map reload	Reload tiles (for grey/missing tiles)

(The !map keyword can be changed via ?cmd=.)

Deploy to GitHub Pages

1. Push the repository to GitHub (already set up: elricco/rtirl-maps-widget).
2. Settings → Pages → Source: Deploy from a branch, branch main, folder / (root).
3. After deploy the widget is available at https://elricco.github.io/rtirl-maps-widget/ — append parameters, done.

Example with a custom border and custom pin:

https://elricco.github.io/rtirl-maps-widget/?pullKey=YOUR_KEY&channel=YOUR_CHANNEL&border=e8352e&borderWidth=6

Troubleshooting: no (live) updates

The widget uses a live subscription (addLocationListener) and follows along on every new push. If it only shows the last/no position, it's usually one of these reasons:

1. Push key missing/wrong in the app. The RealtimeIRL app has no login — it authenticates solely via the push key you enter there. Without a (correct) push key it sends nothing. The push key and the pull key for the widget come from the same web interface (log in there via Twitch) and belong together.
2. App isn't pushing right now (app not in the foreground/active, location not set to "always allow", phone battery saver).
3. Map frozen — someone sent !map freeze; !map follow re-arms it.

How to narrow it down:

• Check upstream: reload https://rtirl.com/api/pull?key=YOUR_PULLKEY several times while moving. If latitude/longitude do not change, it's the app/push key — not the widget.
• Check the widget: open the overlay URL with &debug=1 in a normal browser tab, DevTools → Console. If [rtirl-widget] location … lines appear there, the widget is receiving live; if not, nothing is arriving upstream.

Development

• Tests (pure logic): npm test (uses Node node:test, no dependencies).
• Local testing: python3 -m http.server 8000, then test.html (debug harness with simulated commands/positions) or index.html?pullKey=…&channel=….

---

Deutsch

🇩🇪 Deutsch (unten) · 🇬🇧 English

Ein rundes, ein-/ausblendbares Karten-Widget für Stream-Overlays, das die Live-Position via RealtimeIRL anzeigt und über Twitch-Chat-Commands (Moderatoren & Streamer) gesteuert wird. Reine statische Seite — als GitHub Page hostbar, als OBS-/Overlay-Browser-Source einbindbar.

Einbindung

Als Browser-Source (OBS o. ä.) die gehostete URL mit Parametern verwenden:

https://elricco.github.io/rtirl-maps-widget/?pullKey=DEIN_PULLKEY&channel=DEIN_KANAL

Den Pull Key findest du in deinen RTIRL-Einstellungen.

URL-Parameter

Param	Pflicht	Default	Bedeutung
pullKey	✅	—	RTIRL Pull-Key
channel	✅	—	Twitch-Kanal (für Chat-Commands)
cmd	✗	!map	Command-Keyword
pin	✗	Default	URL zu einem eigenen Marker-Bild
zoom	✗	16	Start-Zoom (1–19)
size	✗	250	Widget-Durchmesser in px
show	✗	0	1 = beim Laden sichtbar starten
border	✗	ffffff	Border-Farbe als Hex, mit oder ohne # (z.B. e8352e, %23000)
borderWidth	✗	4	Border-Dicke in px, 0 = keine Border
debug	✗	0	1 = loggt Config, eingehende Positionen und Chat-Commands in die Browser-Konsole (DevTools)
speed	✗	0	1 = km/h-Anzeige beim Laden aktiviert (analog show)
speedFont	✗	Arial	Google-Font-Name für die km/h-Anzeige (Groß-/Kleinschreibung egal, z.B. Bangers)
speedSize	✗	28	Schriftgröße der km/h-Anzeige in px (8–200)

Hinweis zur speedFont

Der Name wird automatisch in Title Case normalisiert (BANGERS, bangers und Bangers funktionieren alle). Fonts mit ungewöhnlicher Schreibweise (z.B. PT Sans, EB Garamond) müssen exakt so wie bei Google Fonts angegeben werden. Jeden Parameter nur einmal in der URL verwenden – bei doppeltem speedFont zählt der erste Wert.

Hinweis zur pin-URL

Ein schlichter Bild-Link kann direkt angehängt werden – : und / müssen nicht escaped werden:

?pin=https://example.com/mypin.png

Enthält der Link selbst einen Query-String oder Sonderzeichen (&, +, #), muss er einmal komplett prozent-encodiert werden, sonst bricht der & die URL ab bzw. + wird zum Leerzeichen. In der Browser-Konsole: encodeURIComponent("https://example.com/pin.png?v=2&token=abc")

?pin=https%3A%2F%2Fexample.com%2Fpin.png%3Fv%3D2%26token%3Dabc

Chat-Commands (nur Broadcaster & Moderatoren)

Command	Wirkung
!map on	Karte einblenden
!map off	Karte ausblenden
!map off 30	Ausblenden, nach 30 s automatisch wieder einblenden
!map zoom 15	Zoom setzen (1 = weit weg, 19 = ganz nah)
!map follow	Karte folgt der Live-Position (Standard)
!map freeze	Position einfrieren
!map trail on	Route der aktuellen Session als Linie zeigen
!map trail off	Route ausblenden
!map speed on	Geschwindigkeit in km/h unter der Karte einblenden
!map speed off	km/h-Anzeige ausblenden
!map reload	Kacheln neu laden (bei grauen/fehlenden Tiles)

(Keyword !map per ?cmd= änderbar.)

Deploy auf GitHub Pages

1. Repository auf GitHub pushen (bereits eingerichtet: elricco/rtirl-maps-widget).
2. Settings → Pages → Source: Deploy from a branch, Branch main, Ordner / (root).
3. Nach dem Deploy ist das Widget unter https://elricco.github.io/rtirl-maps-widget/ erreichbar — Parameter anhängen, fertig.

Beispiel mit eigener Border und Custom-Pin:

https://elricco.github.io/rtirl-maps-widget/?pullKey=DEIN_KEY&channel=DEIN_KANAL&border=e8352e&borderWidth=6

Fehlersuche: keine (Live-)Updates

Das Widget nutzt ein Live-Abo (addLocationListener) und zieht bei jedem neuen Push nach. Zeigt es nur die letzte/keine Position, meist einer dieser Gründe:

1. Push Key fehlt/falsch in der App. Die RealtimeIRL-App hat keinen Login – sie authentifiziert sich allein über den Push Key, den du dort einträgst. Ohne (richtigen) Push Key sendet sie nichts. Push Key und der Pull Key fürs Widget stammen aus derselben Weboberfläche (dort Login per Twitch) und gehören zusammen.
2. App pusht gerade nicht (App nicht im Vordergrund/aktiv, Standort nicht „immer erlauben", Energiesparmodus des Handys).
3. Karte eingefroren – jemand hat !map freeze geschickt; !map follow schaltet es wieder scharf.

So grenzt du es ein:

• Upstream prüfen: https://rtirl.com/api/pull?key=DEIN_PULLKEY beim Bewegen mehrfach neu laden. Ändern sich latitude/longitude nicht, liegt es an App/Push Key – nicht am Widget.
• Widget prüfen: Overlay-URL mit &debug=1 in einem normalen Browser-Tab öffnen, DevTools → Console. Kommen dort [rtirl-widget] location …-Zeilen, empfängt das Widget live; bleiben sie aus, kommt oben nichts an.

Entwicklung

• Tests (reine Logik): npm test (nutzt Node node:test, keine Dependencies).
• Lokal testen: python3 -m http.server 8000, dann test.html (Debug-Harness mit simulierten Commands/Positionen) oder index.html?pullKey=…&channel=….