Getting Started

What is StreamooS?

StreamooS is a desktop streaming companion app built with Electron. It provides OBS overlays (timer, music player, dock), audio integrations (KHInsider, system media player), Discord Rich Presence, Twitch stream planning, and a mobile remote control -- all from a single dashboard.

Prerequisites

• Node.js 22+
• pnpm 10+ (never use npm or yarn)
• OBS Studio (for overlays)
• Discord desktop running (if Discord RPC is enabled)
• Windows 10+ or Linux (macOS is not supported)

Installation

git clone https://github.com/{Anonyme}/StreamooS.git
cd StreamooS
pnpm install

Environment Variables

Copy .env.example to .env.local and fill in the required values:

# Required
KHINSIDER_URL=https://downloads.khinsider.com/playlist/xxxxx
DISCORD_CLIENT_ID=xxxxxxxxxxxxxxxxxx
STREAMOOS_RENDERER_URL=http://127.0.0.1:5173

Tip: Only KHINSIDER_URL, DISCORD_CLIENT_ID, and STREAMOOS_RENDERER_URL are needed to get started. The rest can be configured later.

Development

pnpm dev

This starts four processes in parallel:

Process	Description	URL
Renderer	Vite dev server (React UI)	http://127.0.0.1:5173
Main	Electron main process (TypeScript watch)	-
Preload	Preload script (TypeScript watch)	-
Electron	Electron app host	-

The embedded WebSocket server listens on ws://127.0.0.1:8765. The Remote Control server (if active) listens on https://0.0.0.0:8080.

Quality Gates (before committing)

pnpm typecheck      # strict TypeScript check
pnpm lint           # ESLint
pnpm build          # full production build
pnpm test:ws-smoke  # WebSocket smoke test

KHInsider option for smoke test:

STREAMOOS_SMOKE_INCLUDE_KHINSIDER=1 pnpm test:ws-smoke

Full Test Suite

pnpm test:unit              # Vitest unit tests
pnpm test:electron:node     # Main process Node.js tests
pnpm test:e2e               # Playwright end-to-end tests
pnpm test:ws-smoke          # WebSocket overlay smoke test

Distribution

pnpm dist:win    # Windows - NSIS installer + portable ZIP
pnpm dist:linux  # Linux - AppImage + DEB

Adding an OBS Overlay

1. In OBS, add a Browser Source

2. Uncheck "Local file" and enter the absolute path:

   file:///C:/Users/you/StreamooS/app/overlays/timer/timer_overlay.html

3. Recommended resolution: 1920x1080

4. Enable "Refresh browser when scene becomes active"

5. The overlay automatically connects to ws://127.0.0.1:8765

Available overlays: Timer, Radio (KHInsider / system player), Dock (full control).

See the OBS Overlays reference for full details.

Troubleshooting

System Tray icon missing

• On Windows, check the overflow area (hidden icons).
• On Linux, ensure you have a libappindicator or libayatana-appindicator compatible desktop environment.

Mobile Remote Control

StreamooS includes a built-in remote control accessible from any device on the same Wi-Fi network:

1. Open the Remote Control section in StreamooS settings
2. Note the displayed URL (e.g. https://192.168.1.x:8080)
3. Open this URL on your mobile browser and pair with the PIN code

See Mobile Remote Setup for detailed instructions.

Troubleshooting

Discord shows nothing

• Check DISCORD_CLIENT_ID in .env.local
• Make sure Discord desktop is running before launching StreamooS
• Look for discord_rpc:connect in the dashboard logs

Overlay not connected

• Check that StreamooS is running (port 8765 open)
• Check WS logs in the OBS console (source=overlay)
• Make sure OBS is using the file:// URL, not http://

KHInsider not playing

• The URL must point to a specific album page, not the homepage
• Check the hidden KHInsider window logs in the dashboard
• The watchdog retries every 5s automatically

No system media detected

• A track must actually be playing in some application (Spotify, YouTube Music, VLC…)
• On Linux the player must expose MPRIS over D-Bus
• On macOS the system source is unsupported (see #314)

Remote control not reachable

• Both devices must be on the same Wi-Fi / LAN network
• Accept the self-signed certificate warning in the mobile browser
• Try the direct IP address if streamoos.local does not resolve