streampal-connect 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# streampal-connect
+
+The one-command agent that links your OBS to your [StreamPal](https://streampal.gg)
+dashboard and phone stream deck.
+
+```bash
+npx streampal-connect <your-pair-code>
+```
+
+Find your pair code on your dashboard at **streampal.gg → OBS**.
+
+It:
+
+- **auto-detects OBS** on this PC (`ws://127.0.0.1:4455`) — asks for the OBS
+  WebSocket password once, then remembers it,
+- connects **outbound** to StreamPal's relay, so your home network needs no
+  port-forwarding or firewall changes,
+- bridges the two: buttons on your dashboard / phone run against OBS here.
+
+Leave the window open while you stream. `Ctrl+C` to stop. Next time it's just
+`npx streampal-connect` — your code and password are saved to
+`~/.streampal/connect.json` (that file never leaves your machine).
+
+## Options
+
+| Flag | Meaning |
+| --- | --- |
+| `--relay <wss://…>` | Use a different relay (default: StreamPal's public relay) |
+| `--obs-url <ws://…>` | OBS WebSocket URL (default `ws://127.0.0.1:4455`) |
+| `--obs-password <pw>` | Pass the OBS password non-interactively |
+| `--reset` | Forget saved settings and set up fresh |
+| `--help` | Show help |
+
+Environment variables `STREAMPAL_PAIR_CODE`, `STREAMPAL_RELAY_URL`,
+`OBS_PASSWORD` are also honoured.
+
+## First-time OBS setup
+
+In OBS: **Tools → WebSocket Server Settings → Enable WebSocket server**. Note
+the password (Show Connect Info). That's the only thing you paste besides your
+pair code.

package/bin/streampal-connect.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+// streampal-connect
+// -----------------
+// The one-command agent. Run it on the PC where OBS lives:
+//
+//   npx streampal-connect <your-pair-code>
+//
+// It auto-detects OBS on localhost, connects OUTBOUND to StreamPal's relay
+// (so your home network needs no port-forwarding), and bridges the two. Press
+// a button on your dashboard / phone stream deck and it runs against OBS here.
+//
+// Nothing is stored on StreamPal's servers except your account's pair code.
+// Your OBS password stays on this machine (~/.streampal/connect.json).
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+const WebSocket = require("ws");
+const { OBSWebSocket } = require("obs-websocket-js");
+
+// -------------------------------------------------------------- tiny ui
+
+const C = {
+  reset: "\x1b[0m", dim: "\x1b[2m", bold: "\x1b[1m",
+  green: "\x1b[32m", red: "\x1b[31m", yellow: "\x1b[33m",
+  cyan: "\x1b[36m", magenta: "\x1b[35m",
+};
+const ok = (m) => console.log(`${C.green}✓${C.reset} ${m}`);
+const warn = (m) => console.log(`${C.yellow}!${C.reset} ${m}`);
+const err = (m) => console.log(`${C.red}✗${C.reset} ${m}`);
+const info = (m) => console.log(`${C.dim}${m}${C.reset}`);
+
+function banner() {
+  console.log(`${C.magenta}${C.bold}
+   ┌────────────────────────────────────┐
+   │        StreamPal  Connect          │
+   └────────────────────────────────────┘${C.reset}`);
+}
+
+// -------------------------------------------------------------- args + config
+
+const argv = process.argv.slice(2);
+function flag(name) {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 ? (argv[i + 1] || "") : undefined;
+}
+const hasFlag = (name) => argv.includes(`--${name}`);
+
+const positional = argv.filter((a) => !a.startsWith("--"));
+// crude: skip values that belong to a flag
+const flagValues = new Set();
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i].startsWith("--") && argv[i + 1] && !argv[i + 1].startsWith("--")) {
+    flagValues.add(argv[i + 1]);
+  }
+}
+const positionalPairCode = positional.find((p) => !flagValues.has(p));
+
+const CONFIG_DIR = path.join(os.homedir(), ".streampal");
+const CONFIG_PATH = path.join(CONFIG_DIR, "connect.json");
+
+function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveConfig(cfg) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  } catch (e) {
+    warn(`couldn't save settings: ${e.message}`);
+  }
+}
+
+if (hasFlag("reset")) {
+  try { fs.unlinkSync(CONFIG_PATH); } catch {}
+  ok("cleared saved settings");
+}
+if (hasFlag("help") || hasFlag("h")) {
+  banner();
+  console.log(`
+  Usage: npx streampal-connect <pair-code> [options]
+
+  Options:
+    --relay <wss://...>     Relay URL (default StreamPal's public relay)
+    --obs-url <ws://...>    OBS WebSocket URL (default ws://127.0.0.1:4455)
+    --obs-password <pw>     OBS WebSocket password (else you'll be asked once)
+    --reset                 Forget saved settings and set up fresh
+    --help                  Show this help
+
+  Your pair code is on your dashboard at streampal.gg → OBS.
+`);
+  process.exit(0);
+}
+
+const cfg = loadConfig();
+
+const DEFAULT_RELAY = process.env.STREAMPAL_RELAY_URL || "wss://relay.streampal.gg";
+const RELAY_URL = (flag("relay") || cfg.relayUrl || DEFAULT_RELAY).replace(/\/$/, "");
+const OBS_URL = flag("obs-url") || cfg.obsUrl || "ws://127.0.0.1:4455";
+let PAIR_CODE = positionalPairCode || process.env.STREAMPAL_PAIR_CODE || cfg.pairCode || "";
+let OBS_PASSWORD =
+  flag("obs-password") !== undefined
+    ? flag("obs-password")
+    : process.env.OBS_PASSWORD !== undefined
+    ? process.env.OBS_PASSWORD
+    : cfg.obsPassword;
+
+// -------------------------------------------------------------- prompts
+
+function ask(question, { hidden = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    if (hidden) {
+      // Mask keystrokes for the OBS password.
+      const onData = (char) => {
+        char = char + "";
+        if (char === "\n" || char === "\r" || char === "") {
+          process.stdin.removeListener("data", onData);
+        } else {
+          readline.clearLine(process.stdout, 0);
+          readline.cursorTo(process.stdout, 0);
+          process.stdout.write(question + "*".repeat(rl.line.length));
+        }
+      };
+      process.stdin.on("data", onData);
+    }
+    rl.question(question, (answer) => {
+      rl.close();
+      if (hidden) process.stdout.write("\n");
+      resolve(answer.trim());
+    });
+  });
+}
+
+// -------------------------------------------------------------- OBS
+
+const obs = new OBSWebSocket();
+let obsConnected = false;
+let relay = null;
+let relayTimer = null;
+
+async function tryObs(url, password) {
+  const client = new OBSWebSocket();
+  try {
+    await client.connect(url, password || undefined);
+    await client.disconnect();
+    return { ok: true };
+  } catch (e) {
+    const msg = (e && e.message) || String(e);
+    // obs-websocket-js: code 4009 == auth failed, 4008 == auth required
+    const authIssue = /authentication|4009|4008|password/i.test(msg);
+    return { ok: false, authIssue, msg };
+  }
+}
+
+async function ensureObsCredentials() {
+  info(`Looking for OBS at ${OBS_URL} …`);
+  let probe = await tryObs(OBS_URL, OBS_PASSWORD);
+  if (probe.ok) {
+    ok("found OBS");
+    return;
+  }
+  if (!probe.authIssue) {
+    warn("OBS isn't reachable yet — make sure OBS is open and its WebSocket");
+    warn("server is enabled (Tools → WebSocket Server Settings). I'll keep trying.");
+    return; // connectOBS() will retry in the loop
+  }
+  // Auth problem — ask for the password (once) and re-probe.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    warn("OBS needs its WebSocket password.");
+    info("Find it in OBS → Tools → WebSocket Server Settings → Show Connect Info.");
+    const pw = await ask(`${C.cyan}OBS password: ${C.reset}`, { hidden: true });
+    OBS_PASSWORD = pw;
+    probe = await tryObs(OBS_URL, OBS_PASSWORD);
+    if (probe.ok) {
+      ok("password accepted");
+      return;
+    }
+    err("that password didn't work — try again");
+  }
+  err("couldn't authenticate with OBS. Run again with the right password.");
+  process.exit(1);
+}
+
+async function connectOBS() {
+  try {
+    await obs.connect(OBS_URL, OBS_PASSWORD || undefined);
+    obsConnected = true;
+    ok(`OBS connected (${OBS_URL})`);
+    pushStatus();
+  } catch (e) {
+    obsConnected = false;
+    info(`waiting for OBS … (${e.message})`);
+    setTimeout(connectOBS, 5000);
+  }
+}
+
+obs.on("ConnectionClosed", () => {
+  if (!obsConnected) return;
+  obsConnected = false;
+  warn("OBS closed — reconnecting");
+  pushStatus();
+  setTimeout(connectOBS, 5000);
+});
+
+// keep dashboard buttons in sync with changes made directly in OBS
+obs.on("StreamStateChanged", (d) => toRelay({ type: "event", event: "stream", active: d.outputActive }));
+obs.on("RecordStateChanged", (d) => toRelay({ type: "event", event: "record", active: d.outputActive }));
+obs.on("CurrentProgramSceneChanged", (d) => toRelay({ type: "event", event: "scene", scene: d.sceneName }));
+obs.on("InputMuteStateChanged", (d) => toRelay({ type: "event", event: "mute", inputName: d.inputName, muted: d.inputMuted }));
+obs.on("VirtualcamStateChanged", (d) => toRelay({ type: "event", event: "virtualcam", active: d.outputActive }));
+obs.on("ReplayBufferStateChanged", (d) => toRelay({ type: "event", event: "replay", active: d.outputActive }));
+
+// -------------------------------------------------------------- relay
+
+let relayReady = false;
+
+function connectRelay() {
+  const url = `${RELAY_URL}/?role=agent&code=${encodeURIComponent(PAIR_CODE)}`;
+  info(`Connecting to relay …`);
+  relay = new WebSocket(url);
+
+  relay.on("open", () => {
+    relayReady = true;
+    ok("relay connected — your dashboard can now control OBS");
+    console.log(`${C.dim}   Leave this window open while you stream. Ctrl+C to stop.${C.reset}`);
+    pushStatus();
+  });
+  relay.on("message", (raw) => {
+    let msg;
+    try { msg = JSON.parse(raw.toString()); } catch { return; }
+    if (msg.type === "command") handleCommand(msg);
+  });
+  relay.on("close", (code) => {
+    if (relayReady) warn("relay disconnected — reconnecting");
+    else if (code === 1008 || code === 4401) {
+      err("relay rejected the pair code. Copy it again from streampal.gg → OBS.");
+      process.exit(1);
+    }
+    relayReady = false;
+    scheduleRelayReconnect();
+  });
+  relay.on("error", (e) => {
+    if (!relayReady) err(`relay error: ${e.message}`);
+  });
+}
+function scheduleRelayReconnect() {
+  if (relayTimer) return;
+  relayTimer = setTimeout(() => { relayTimer = null; connectRelay(); }, 3000);
+}
+function toRelay(obj) {
+  if (relay && relay.readyState === WebSocket.OPEN) relay.send(JSON.stringify(obj));
+}
+function pushStatus() {
+  toRelay({ type: "obs-status", connected: obsConnected });
+}
+
+// -------------------------------------------------------------- commands
+
+async function handleCommand(msg) {
+  const { id, action, params } = msg;
+  try {
+    let data;
+    if (action === "snapshot") {
+      const sceneList = await obs.call("GetSceneList");
+      let streaming = false, recording = false, virtualCam = false, replayBuffer = false;
+      try { streaming = (await obs.call("GetStreamStatus")).outputActive; } catch {}
+      try { recording = (await obs.call("GetRecordStatus")).outputActive; } catch {}
+      try { virtualCam = (await obs.call("GetVirtualCamStatus")).outputActive; } catch {}
+      try { replayBuffer = (await obs.call("GetReplayBufferStatus")).outputActive; } catch {}
+      const audioInputs = [];
+      try {
+        const { inputs } = await obs.call("GetInputList");
+        for (const input of inputs) {
+          try {
+            const { inputMuted } = await obs.call("GetInputMute", { inputName: input.inputName });
+            audioInputs.push({ name: input.inputName, muted: inputMuted });
+          } catch { /* not an audio input */ }
+        }
+      } catch {}
+      data = {
+        scenes: sceneList.scenes.map((s) => s.sceneName).reverse(),
+        currentScene: sceneList.currentProgramSceneName,
+        streaming, recording, virtualCam, replayBuffer, audioInputs,
+      };
+    } else {
+      data = await obs.call(action, params || {});
+    }
+    toRelay({ type: "result", id, ok: true, data });
+  } catch (e) {
+    err(`"${action}" failed: ${e.message}`);
+    toRelay({ type: "result", id, ok: false, error: e.message });
+  }
+}
+
+// -------------------------------------------------------------- boot
+
+async function main() {
+  banner();
+
+  if (!PAIR_CODE) {
+    info("Find your pair code on your dashboard: streampal.gg → OBS.");
+    PAIR_CODE = await ask(`${C.cyan}Pair code: ${C.reset}`);
+    if (!PAIR_CODE) {
+      err("a pair code is required.");
+      process.exit(1);
+    }
+  }
+
+  await ensureObsCredentials();
+
+  // Persist what we learned so next time it's truly one command.
+  saveConfig({
+    pairCode: PAIR_CODE,
+    obsUrl: OBS_URL,
+    obsPassword: OBS_PASSWORD || "",
+    relayUrl: RELAY_URL === DEFAULT_RELAY ? undefined : RELAY_URL,
+  });
+
+  console.log();
+  info(`relay : ${RELAY_URL}`);
+  info(`obs   : ${OBS_URL}`);
+  info(`code  : ${PAIR_CODE.slice(0, 6)}…`);
+  console.log();
+
+  connectOBS();
+  connectRelay();
+}
+
+process.on("SIGINT", () => {
+  console.log(`\n${C.dim}Stopping StreamPal Connect. Bye!${C.reset}`);
+  process.exit(0);
+});
+
+main().catch((e) => {
+  err(e.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "streampal-connect",
+  "version": "1.0.0",
+  "description": "Link your OBS to your StreamPal dashboard. Runs on your streaming PC and connects outbound to StreamPal's relay — no port-forwarding, no config.",
+  "keywords": ["streampal", "obs", "obs-websocket", "streaming", "stream-deck"],
+  "homepage": "https://streampal.gg/download",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "streampal-connect": "bin/streampal-connect.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "obs-websocket-js": "^5.0.6",
+    "ws": "^8.18.0"
+  }
+}