@single-studio/plugin-obs 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Shaun Delaney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @single-studio/plugin-obs
+
+OBS for [Single Studio](https://fourcourtjester.github.io/Single-Studio/): the live
+scene, stream and record state, straight into a studio over obs-websocket.
+
+```bash
+npm i @single-studio/plugin-obs
+```
+
+```js
+// src/studio/velcro.worker.js
+import { obs, OBSHandler } from '@single-studio/plugin-obs'
+
+class MyShow extends OBSHandler {
+  onScene({ name }) {
+    this.mutate('set', { 'variables.scene': name })
+  }
+}
+
+createVelcroHost({ name: STUDIO_ID, mutations, plugins: [obs(MyShow)] })
+```
+
+The operator sets the host, port and password on their own board, under **Plugins** —
+those belong to the machine, not to the build. OBS: **Tools → WebSocket Server
+Settings**.
+
+## What it tells you
+
+| Method | When |
+| --- | --- |
+| `onConnected` | the connection is up and identified |
+| `onScene` | the programme scene changed |
+| `onPreview` | the preview scene changed (studio mode) |
+| `onSourceVisibility` | a source was shown or hidden |
+| `onStream` / `onRecord` | streaming or recording started or stopped |
+| `onMute` | an audio input was muted or unmuted |
+| `onTransitionStarted` / `onTransitionEnded` | a transition ran |
+| `onExit` | OBS is shutting down |
+
+## What you can ask it
+
+```js
+this.command('scene', { name: 'Podium' })
+```
+
+And from anywhere else in a studio — a mutation, another plugin's handler:
+
+```js
+ctx.ask('obs', 'scene', { name: 'Podium' })
+```
+
+`ask` when you want the answer back rather than fire-and-forget:
+
+```js
+const { sceneItemId } = await this.look('obs', 'GetSceneItemId', { sceneName: 'Match', sourceName: 'cam' })
+```
+
+That one exists because OBS assigns `sceneItemId` when a source is added to a scene
+and changes it if the source is removed and put back — so it cannot be written down
+anywhere and has to be looked up from the name somebody typed.
+
+## Licence
+
+MIT.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@single-studio/plugin-obs",
+  "version": "0.6.0",
+  "description": "OBS for Single Studio: the live scene, stream and record state, straight into a studio over obs-websocket.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FourCourtJester/Single-Studio.git",
+    "directory": "packages/plugin-obs"
+  },
+  "homepage": "https://github.com/FourCourtJester/Single-Studio#readme",
+  "bugs": "https://github.com/FourCourtJester/Single-Studio/issues",
+  "type": "module",
+  "keywords": [
+    "single-studio",
+    "single-studio-plugin",
+    "obs",
+    "broadcast"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@single-studio/core": "^0.6.0"
+  },
+  "devDependencies": {
+    "@single-studio/core": "workspace:*",
+    "vitest": "^3.2.6"
+  }
+}

package/src/events.js

@@ -0,0 +1,92 @@
+// OBS's events, in the shape a studio would have written.
+//
+// Field names come from obs-websocket's own protocol reference. The reshaping is
+// small on purpose -- OBS is already close to readable -- and is mostly about two
+// things: dropping the UUIDs nobody addresses anything by, and turning
+// `outputActive` plus `outputState` into the one word a graphic reads.
+
+/**
+ * `outputState` is a string like `OBS_WEBSOCKET_OUTPUT_STARTING`, which is precise
+ * and not something to put in a template. `outputActive` alone loses the difference
+ * between starting and started, and a "LIVE" badge that lights up during the
+ * handshake is on air before the stream is.
+ */
+const stateOf = (data) => {
+  const raw = String(data?.outputState ?? '')
+  const word = raw.replace('OBS_WEBSOCKET_OUTPUT_', '').toLowerCase()
+
+  return {
+    active: Boolean(data?.outputActive),
+    state: word || (data?.outputActive ? 'started' : 'stopped'),
+    // The two that matter for a badge: only `started` is genuinely on air.
+    live: word === 'started',
+    settling: word === 'starting' || word === 'stopping',
+  }
+}
+
+export const EVENTS = {
+  CurrentProgramSceneChanged: {
+    emit: 'scene',
+    category: 'scenes',
+    shape: (data) => ({ name: data?.sceneName ?? null }),
+  },
+  CurrentPreviewSceneChanged: {
+    emit: 'preview',
+    category: 'scenes',
+    shape: (data) => ({ name: data?.sceneName ?? null }),
+  },
+  SceneItemEnableStateChanged: {
+    emit: 'sourceVisibility',
+    category: 'sceneItems',
+    shape: (data) => ({ scene: data?.sceneName ?? null, itemId: data?.sceneItemId ?? null, visible: Boolean(data?.sceneItemEnabled) }),
+  },
+  StreamStateChanged: {
+    emit: 'stream',
+    category: 'outputs',
+    shape: stateOf,
+  },
+  RecordStateChanged: {
+    emit: 'record',
+    category: 'outputs',
+    shape: (data) => ({ ...stateOf(data), path: data?.outputPath ?? null }),
+  },
+  InputMuteStateChanged: {
+    emit: 'mute',
+    category: 'inputs',
+    shape: (data) => ({ input: data?.inputName ?? null, muted: Boolean(data?.inputMuted) }),
+  },
+  SceneTransitionStarted: {
+    emit: 'transitionStarted',
+    category: 'transitions',
+    shape: (data) => ({ transition: data?.transitionName ?? null }),
+  },
+  SceneTransitionEnded: {
+    emit: 'transitionEnded',
+    category: 'transitions',
+    shape: (data) => ({ transition: data?.transitionName ?? null }),
+  },
+  ExitStarted: {
+    emit: 'exit',
+    category: 'general',
+    shape: () => ({}),
+  },
+}
+
+/** The categories the wanted events live in, as one bitmask's worth of names. */
+export const categoriesFor = (types = Object.keys(EVENTS)) => [...new Set(types.map((type) => EVENTS[type]?.category).filter(Boolean))]
+
+/**
+ * One OBS event, as the event a studio hears.
+ *
+ * Unknown types pass through under their own name with the payload untouched, so a
+ * studio wanting something this table has not caught up with is not blocked on a
+ * release.
+ */
+export function normalise(type, data) {
+  const known = EVENTS[type]
+
+  return {
+    name: known?.emit ?? type,
+    payload: { ...(known ? known.shape(data) : {}), raw: data },
+  }
+}

package/src/index.js

@@ -0,0 +1,256 @@
+import { definePlugin, PluginHandler, SocketService } from '@single-studio/core/worker'
+
+import { categoriesFor, EVENTS, normalise } from './events.js'
+import { authenticate, classify, identify, maskOf, request } from './protocol.js'
+
+export { CATEGORY, OP, authenticate, classify, maskOf } from './protocol.js'
+export { EVENTS, categoriesFor, normalise } from './events.js'
+
+/**
+ * OBS, over obs-websocket, in the SharedWorker.
+ *
+ * The one every studio wants and the one nobody thinks of first, because OBS is
+ * where the studio already lives. Knowing which scene is live lets a graphic decide
+ * for itself: a lower third that hides when the camera cuts away, a scoreboard that
+ * only counts while the match scene is up, a "LIVE" badge that is honest.
+ *
+ * Requests were always here, because reading needs them: OBS announces changes and
+ * never announces the present, so a studio that only listened would not know the
+ * scene until somebody changed it. The plugin asks once on connect.
+ *
+ * A handful of them are now declared as commands, so a studio can answer as well as
+ * listen -- cut the scene when the whistle goes. What is still deferred is a
+ * *remote* operator pressing a button, which is a routing problem rather than a
+ * protocol one. See architecture.md#commands.
+ */
+class OBS extends SocketService {
+  static serviceName = 'obs'
+
+  /**
+   * What a studio can ask OBS to do.
+   *
+   * A deliberately small list: the things a show does *to itself* while it is
+   * running. OBS accepts a hundred-odd requests and most of them configure it --
+   * creating scenes, moving sources, setting up encoders -- which is the operator's
+   * job at build time and not something a graphic should be doing at five to seven.
+   *
+   * `requestId` is a constant rather than a counter because nothing waits for the
+   * reply. `ask` correlates because it has a promise to settle; a command is told,
+   * not asked, and OBS ignores an id it is not being asked about.
+   */
+  static commands = {
+    /** Cut to a scene by name. The one everybody wants. */
+    scene: ({ name }) => request('SetCurrentProgramScene', 'ss-cmd', { sceneName: name }),
+
+    /** Load a scene into preview, for a studio-mode operator to take manually. */
+    preview: ({ name }) => request('SetCurrentPreviewScene', 'ss-cmd', { sceneName: name }),
+
+    stream: ({ on }) => request(on ? 'StartStream' : 'StopStream', 'ss-cmd'),
+    record: ({ on }) => request(on ? 'StartRecord' : 'StopRecord', 'ss-cmd'),
+    pauseRecord: ({ on }) => request(on ? 'PauseRecord' : 'ResumeRecord', 'ss-cmd'),
+
+    /** Show or hide one source within a scene. Needs the scene's item id. */
+    item: ({ scene, id, visible }) => request('SetSceneItemEnabled', 'ss-cmd', { sceneName: scene, sceneItemId: id, sceneItemEnabled: Boolean(visible) }),
+  }
+
+  #pending = new Map()
+
+  #nextId = 0
+
+  /** Not usable until identified, so `open()` waits for that rather than the socket. */
+  get readyOnOpen() {
+    return false
+  }
+
+  get types() {
+    const asked = String(this.config.events ?? '')
+      .split(',')
+      .map((type) => type.trim())
+      .filter(Boolean)
+
+    return asked.length ? asked : Object.keys(EVENTS)
+  }
+
+  get url() {
+    const host = this.config.host || 'localhost'
+    const port = Number(this.config.port) || 4455
+
+    return `ws://${host}:${port}`
+  }
+
+  async receive(raw) {
+    const action = classify(raw)
+
+    switch (action.do) {
+      case 'identify': {
+        // A password is only needed when OBS asks. Sending one it did not ask for
+        // is refused, and refusing to connect because a studio left the field empty
+        // would be wrong for the common case of authentication switched off.
+        if (action.auth && !this.config.password) {
+          this.fail(new Error('OBS is asking for a password, and none is set.'))
+
+          return
+        }
+
+        const authentication = action.auth ? await authenticate(this.config.password, action.auth.salt, action.auth.challenge) : undefined
+
+        this.send(
+          identify({
+            rpcVersion: action.rpcVersion,
+            authentication,
+            eventSubscriptions: maskOf(categoriesFor(this.types)),
+          }),
+        )
+
+        return
+      }
+
+      case 'ready':
+        this.emit('connected', { rpcVersion: action.rpcVersion })
+
+        // OBS announces changes and never announces the present. Without this a
+        // studio does not know the scene until somebody changes it -- which on a
+        // quiet show could be the whole broadcast.
+        this.#prime().then(
+          () => this.ready(),
+          () => this.ready(),
+        )
+
+        return
+
+      case 'event': {
+        const { name, payload } = normalise(action.type, action.data)
+
+        this.emit(name, payload)
+        this.emit('*', name, payload)
+
+        return
+      }
+
+      case 'response': {
+        const settle = this.#pending.get(action.id)
+
+        this.#pending.delete(action.id)
+        settle?.(action)
+
+        return
+      }
+
+      default:
+    }
+  }
+
+  /**
+   * Ask something and wait for the matching reply.
+   *
+   * Correlated by `requestId` rather than by order: OBS may answer out of order,
+   * and matching on arrival would attach one reply to another request's promise.
+   */
+  ask(requestType, requestData) {
+    const id = `ss-${(this.#nextId += 1)}`
+
+    return new Promise((resolve) => {
+      this.#pending.set(id, resolve)
+      this.send(request(requestType, id, requestData))
+    })
+  }
+
+  /** Read the present, once, so the first paint is not a guess. */
+  async #prime() {
+    const scene = await this.ask('GetCurrentProgramScene')
+
+    if (scene.ok) this.emit('scene', { name: scene.data.currentProgramSceneName ?? scene.data.sceneName ?? null, raw: scene.data })
+
+    const stream = await this.ask('GetStreamStatus')
+
+    if (stream.ok) {
+      this.emit('stream', {
+        active: Boolean(stream.data.outputActive),
+        state: stream.data.outputActive ? 'started' : 'stopped',
+        live: Boolean(stream.data.outputActive),
+        settling: false,
+        raw: stream.data,
+      })
+    }
+  }
+
+  async close() {
+    this.#pending.clear()
+    await super.close()
+  }
+}
+
+/** The skeleton a studio fills in. One method per event, all no-ops. */
+export class OBSHandler extends PluginHandler {
+  static handles = {
+    connected: 'onConnected',
+    scene: 'onScene',
+    preview: 'onPreview',
+    sourceVisibility: 'onSourceVisibility',
+    stream: 'onStream',
+    record: 'onRecord',
+    mute: 'onMute',
+    transitionStarted: 'onTransitionStarted',
+    transitionEnded: 'onTransitionEnded',
+    exit: 'onExit',
+  }
+
+  onConnected() {}
+
+  onScene() {}
+
+  onPreview() {}
+
+  onSourceVisibility() {}
+
+  onStream() {}
+
+  onRecord() {}
+
+  onMute() {}
+
+  onTransitionStarted() {}
+
+  onTransitionEnded() {}
+
+  onExit() {}
+}
+
+/** @param {typeof OBSHandler} [Handler] */
+export const obs = (Handler = OBSHandler) =>
+  definePlugin({
+    name: 'obs',
+    label: 'OBS',
+    summary: 'Reads the live scene, and whether you are streaming or recording.',
+    help: [
+      { type: 'text', text: 'OBS can already do this — there is nothing to install. It just has to be switched on.' },
+      {
+        type: 'steps',
+        items: [
+          'In OBS, open Tools → WebSocket Server Settings.',
+          'Tick "Enable WebSocket server".',
+          'Leave the port as 4455 unless you have a reason to change it.',
+          'If "Enable Authentication" is ticked, press "Show Connect Info" and copy the password into the field above. If it is not ticked, leave the password blank.',
+          'Press Apply, then Save and reconnect here.',
+        ],
+      },
+      { type: 'note', text: 'Running OBS on another machine? Put its address in Host, and make sure that machine allows the connection through its firewall.' },
+      {
+        type: 'text',
+        text: 'Once connected, your graphics can react to the scene that is live — a lower third that hides itself when the camera cuts away, or a badge that only shows while you are actually streaming.',
+      },
+    ],
+    config: [
+      { key: 'host', label: 'Host', default: 'localhost', help: 'The machine running OBS. Usually this one.' },
+      { key: 'port', label: 'Port', type: 'number', default: 4455, help: 'Tools → WebSocket Server Settings.' },
+      { key: 'password', label: 'Password', type: 'secret', help: 'Only if OBS is asking for one.' },
+      { key: 'events', label: 'Events', help: 'Comma separated. Blank for all of them.' },
+    ],
+    create: (context) => {
+      const plugin = new OBS(context)
+
+      new Handler({ ...context, plugin }).attach(plugin.events)
+
+      return plugin
+    },
+  })

package/src/protocol.js

@@ -0,0 +1,146 @@
+// obs-websocket v5, as data and pure functions with no socket in them.
+//
+// Verified against obsproject/obs-websocket docs/generated/protocol.md rather than
+// written from memory. The parts that are easy to get subtly wrong -- the auth
+// hash, the subscription bitmask, request correlation -- are all here, where a test
+// can check them against the worked example in that document.
+
+/** Opcodes, both directions. */
+export const OP = {
+  HELLO: 0,
+  IDENTIFY: 1,
+  IDENTIFIED: 2,
+  REIDENTIFY: 3,
+  EVENT: 5,
+  REQUEST: 6,
+  RESPONSE: 7,
+  BATCH: 8,
+  BATCH_RESPONSE: 9,
+}
+
+/**
+ * Event categories, as a bitmask.
+ *
+ * Deliberately not `All`. Its value has changed -- `Canvases` joined it in
+ * obs-websocket 5.7.0 -- so "all" means different numbers to different versions of
+ * OBS, and asking for categories a studio does not read is paying for events that
+ * cross the socket to be discarded. A studio subscribes to what it uses.
+ *
+ * The high-volume ones are above 1 << 15 and are never included by default, by
+ * OBS's own rule: `InputVolumeMeters` alone is dozens of messages a second.
+ */
+export const CATEGORY = {
+  none: 0,
+  general: 1 << 0,
+  config: 1 << 1,
+  scenes: 1 << 2,
+  inputs: 1 << 3,
+  transitions: 1 << 4,
+  filters: 1 << 5,
+  outputs: 1 << 6,
+  sceneItems: 1 << 7,
+  mediaInputs: 1 << 8,
+  vendors: 1 << 9,
+  ui: 1 << 10,
+  canvases: 1 << 11,
+}
+
+/**
+ * @param {string[]} names
+ * @returns {number}
+ */
+export const maskOf = (names = []) => names.reduce((mask, name) => mask | (CATEGORY[name] ?? 0), 0)
+
+const b64 = (bytes) => {
+  let binary = ''
+
+  for (const byte of new Uint8Array(bytes)) binary += String.fromCharCode(byte)
+
+  return btoa(binary)
+}
+
+const sha256 = async (text) => b64(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)))
+
+/**
+ * The answer to OBS's challenge.
+ *
+ * Two rounds, and the order matters in both: the password is hashed with the salt
+ * to make a secret, and that secret -- base64, not raw bytes -- is hashed with the
+ * challenge. Concatenating in the other order, or hashing the raw digest rather
+ * than its base64, produces a string that is the right length and always wrong.
+ *
+ * @param {string} password
+ * @param {string} salt
+ * @param {string} challenge
+ * @returns {Promise<string>}
+ */
+export async function authenticate(password, salt, challenge) {
+  const secret = await sha256(password + salt)
+
+  return sha256(secret + challenge)
+}
+
+/**
+ * What to do about a message from OBS.
+ *
+ * @param {unknown} raw Already JSON.parse'd.
+ */
+export function classify(raw) {
+  const op = raw?.op
+  const d = raw?.d
+
+  switch (op) {
+    case OP.HELLO:
+      return {
+        do: 'identify',
+        rpcVersion: d?.rpcVersion ?? 1,
+        // Absent when OBS has authentication switched off, which is a normal
+        // configuration and not an error.
+        auth: d?.authentication ?? null,
+        obs: d?.obsStudioVersion ?? null,
+        websocket: d?.obsWebSocketVersion ?? null,
+      }
+
+    case OP.IDENTIFIED:
+      return { do: 'ready', rpcVersion: d?.negotiatedRpcVersion ?? null }
+
+    case OP.EVENT:
+      return { do: 'event', type: d?.eventType ?? null, data: d?.eventData ?? {} }
+
+    case OP.RESPONSE:
+      return {
+        do: 'response',
+        id: d?.requestId ?? null,
+        ok: Boolean(d?.requestStatus?.result),
+        // `comment` is the only thing that says *why*, and it is absent on success.
+        reason: d?.requestStatus?.comment ?? d?.requestStatus?.code ?? null,
+        data: d?.responseData ?? {},
+      }
+
+    default:
+      return { do: 'ignore', reason: `unhandled opcode ${op}` }
+  }
+}
+
+/**
+ * The Identify frame.
+ *
+ * @param {object} options
+ * @param {number} options.rpcVersion
+ * @param {string} [options.authentication]
+ * @param {number} options.eventSubscriptions
+ */
+export const identify = ({ rpcVersion, authentication, eventSubscriptions }) => ({
+  op: OP.IDENTIFY,
+  d: {
+    rpcVersion,
+    ...(authentication ? { authentication } : {}),
+    eventSubscriptions,
+  },
+})
+
+/** A request frame. `requestId` is what correlates the reply. */
+export const request = (requestType, requestId, requestData) => ({
+  op: OP.REQUEST,
+  d: { requestType, requestId, ...(requestData ? { requestData } : {}) },
+})