Mobile Remote

StreamooS can be controlled from a mobile device on the local network via a PWA (Progressive Web App).

Prerequisites

• PC and mobile on the same Wi-Fi network
• StreamooS running (the remote server starts automatically)

Access

1. In StreamooS settings, note the displayed address (e.g. https://streamoos.local:8080 or https://192.168.1.x:8080)
2. Open that URL in your mobile browser

PIN Pairing

Security

The JWT token is signed using a unique 32-byte secret generated per installation and stored encrypted via safeStorage. This ensures that even on a local network, unauthorized devices cannot forge control tokens.

On first access, a PIN code is displayed in the desktop app. Enter it on mobile to validate pairing. A JWT token is then stored on the mobile for future connections.

HTTPS and Self-Signed Certificates

The PWA requires HTTPS. StreamooS automatically generates a self-signed certificate in userData/.

On iOS (Safari)

1. Accept the security warning: Advanced -> Continue to site
2. Share -> Add to Home Screen

On Android (Chrome)

Certificate Trust

Since the certificate is self-signed and generated locally, your browser will show a security warning. This is expected for local network HTTPS. You must manually "Proceed" or "Trust" the certificate to allow the PWA to communicate with the StreamooS server.

1. Accept the warning: Advanced -> Proceed to site
2. ⋮ menu -> Install app

Technical Architecture

Mobile (PWA) ──HTTPS:8080──▶ Fastify (app/src/main/remote/)
                                      │
                              HandlerRuntime.dispatchCommand()
                                      │
                              FeatureHandlers (timer, khinsider...)

• Discovery: mDNS via DiscoveryService -> streamoos.local
• Auth: JWT signed by AuthService after PIN pairing
• Commands: filtered by an explicit allowlist (REMOTE_SAFE_COMMANDS in app/src/main/remote/server.ts) - only the actions listed below reach the feature handlers

Available Controls

Once paired, the remote PWA exposes the actions below. The allowlist in app/src/main/remote/server.ts (REMOTE_SAFE_COMMANDS) is the source of truth; this table mirrors it. Anything not listed (arbitrary config edits, dangerous commands, features outside the list) is rejected at the server boundary.

Feature	Available Actions
KHInsider Radio	Play, Pause, Next, Shuffle, Volume, Activate, Deactivate, Restart, Diagnostic
SMTC	Play, Pause, Toggle, Next, Previous, Select source (radio pin or media session)
Timer	Start, Stop, Reset, Skip phase
Tasks	Add, Toggle, Remove, Reorder, Clear
Discord	Connect, Disconnect, Status
Twitch	Chat send, Test alert, Trigger flow, Recent events, Live/session/trend stats, Channel points (list), Stream presets (get + apply), Raid start/cancel, Poll create, Prediction create
Overlays	Show/hide toggle per overlay (Timer, Tasks, SMTC) - config stays read-only over remote

Current state (now playing, timer, tasks, alert feed, overlay visibility) replays automatically on every connect, so the PWA always opens on the real state without extra requests.

Port Fallback

The Remote Server tries port 8080 first, then 8443 if 8080 is busy. The QR code and the URL shown in the dashboard always reflect the actual port - scan or copy them rather than typing the address from memory. If both ports are busy, the dashboard shows an explicit error on the Remote card; close the application using those ports and generate a new PIN.

Paired Devices

The Remote card lists every paired device (name + last activity). Use Revoke to invalidate a device's access immediately - it will need to pair again with a new PIN.

Troubleshooting

Browser error	Likely cause	Fix
DNS_PROBE_FINISHED_NXDOMAIN on streamoos.local	mDNS blocked by router/OS (common on Windows without Bonjour, some Android versions)	Use the fallback IP URL encoded in the QR code (https://192.168.x.x:<port>)
ERR_CERT_AUTHORITY_INVALID / certificate warning	Self-signed certificate (expected)	Accept the certificate manually - see the HTTPS section above
ERR_CONNECTION_REFUSED	Server not running (both ports busy) or firewall	Check the status on the Remote card, free ports 8080/8443, open the port in the firewall
Pairing fails with a valid PIN	PIN expired (5 min) or already consumed	Generate a new PIN from the dashboard
Remote stops responding after app restart	Pairings are kept in memory only	Pair again with a new PIN

mDNS

Some routers block mDNS. In that case, scan the QR code: it encodes the direct LAN IP URL, which bypasses name resolution entirely.

Firewall

If the remote is not reachable, ensure ports 8080/8443 (HTTPS) are open in your firewall. On Windows, StreamooS may prompt for a firewall exception on first launch.

A page that stays black then times out (no error) means packets are silently dropped by a firewall:

• Windows Defender: allow StreamooS on the network profile in use (Ethernet is often classified Public).
• Portmaster: its global Force Block Incoming Connections wins over Windows rules. In Portmaster, open the StreamooS app (electron.exe in dev) and add the incoming rule + LAN.
• VPN adapters (Tailscale, WSL): StreamooS advertises the home LAN address (192.168.x.x first), never a 169.254.x.x link-local one. If the QR shows another address, check which network the phone is on (guest Wi-Fi and AP isolation block LAN access).