obs-scheduler 0.0.1

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edon
+
+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,36 @@
+# obs-scheduler
+
+A CLI for scheduling actions in OBS.
+
+## Usage
+
+```shell
+obs-scheduler -c scheduler-config.json -p 
+```
+
+## Examples
+
+### Configuration File
+
+```json
+{
+  "events": [
+    {
+      "name": "Example Event",
+      "schedule_type": "date",
+      "date": "2026-01-06T10:00",
+      "action": "start_recording"
+    },
+    {
+      "name": "Example Event 2",
+      "schedule_type": "recurring",
+      "schedule": "* * * * * *",
+      "action": "start_recording"
+    }
+  ]
+}
+```
+
+## Notes
+
+`config-schema.json` takes advantage of options and syntax from [`json-editor`](https://github.com/json-editor/json-editor) to allow for easy integration into a visual editor.

package/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { run } from "./dist/index.js";
+
+import { program } from "commander";
+
+program
+    .name('obs-scheduler')
+    .version('0.0.1')
+    .option('-c, --config <file-path>', 'config file path')
+    .option(
+        '-i, --ip-address [address:port]',
+        'OBS Websocket IP address and port',
+        undefined,
+    )
+    .option(
+        '-p, --password [password]',
+        'OBS Websocket password',
+        undefined,
+    )
+    .action(run);
+
+await program.parseAsync(process.argv);

package/config-schema.json

@@ -0,0 +1,216 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OBS Scheduler Config File Schema",
+  "type": "object",
+  "required": [
+    "events"
+  ],
+  "properties": {
+    "events": {
+      "title": "Events",
+      "description": "A list of events for triggering an action within OBS.",
+      "type": "array",
+      "format": "tabs",
+      "items": {
+        "title": "Event",
+        "description": "A scheduled event for triggering a set action in OBS.",
+        "type": "object",
+        "required": [
+          "schedule_type",
+          "action"
+        ],
+        "properties": {
+          "name": {
+            "title": "Name",
+            "description": "An optional name for the event.",
+            "propertyOrder": 1,
+            "type": "string"
+          },
+          "enabled": {
+            "title": "Enabled",
+            "description": "Whether or not this event should be considered \"active\".",
+            "propertyOrder": 2,
+            "type": "boolean",
+            "default": true,
+            "format": "checkbox"
+          },
+          "schedule_type": {
+            "title": "Schedule Type",
+            "propertyOrder": 3,
+            "$ref": "#/definitions/ScheduleType"
+          },
+          "date": {
+            "title": "Date",
+            "description": "A date/time for when the action should trigger.",
+            "propertyOrder": 4,
+            "type": "string",
+            "format": "datetime-local",
+            "options": {
+              "dependencies": {
+                "schedule_type": "date"
+              }
+            }
+          },
+          "schedule": {
+            "title": "Schedule",
+            "description": "[WIP] A schedule for a recurring event.",
+            "propertyOrder": 4,
+            "type": "string",
+            "options": {
+              "dependencies": {
+                "schedule_type": "recurring"
+              }
+            }
+          },
+          "action": {
+            "title": "Action",
+            "propertyOrder": 5,
+            "$ref": "#/definitions/EventAction"
+          },
+          "switcher_message": {
+            "title": "Advanced Scene Switcher Message",
+            "description": "A message to send to Advanced Scene Switcher.",
+            "type": "string",
+            "options": {
+              "dependencies": {
+                "action": "advanced_scene_switcher"
+              }
+            }
+          },
+          "ws_request": {
+            "title": "OBS Websocket Message",
+            "$ref": "#/definitions/OBSWSRequest"
+          }
+        },
+        "allOf": [
+          {
+            "oneOf": [
+              {
+                "required": [
+                  "date"
+                ],
+                "properties": {
+                  "schedule_type": {
+                    "const": "date"
+                  }
+                }
+              },
+              {
+                "required": [
+                  "schedule"
+                ],
+                "properties": {
+                  "schedule_type": {
+                    "const": "recurring"
+                  }
+                }
+              }
+            ]
+          },
+          {
+            "oneOf": [
+              {
+                "not": {
+                  "properties": {
+                    "action": {
+                      "enum": [
+                        "advanced_scene_switcher",
+                        "obs_ws"
+                      ]
+                    }
+                  }
+                }
+              },
+              {
+                "required": [
+                  "switcher_message"
+                ],
+                "properties": {
+                  "action": {
+                    "const": "advanced_scene_switcher"
+                  }
+                }
+              },
+              {
+                "required": [
+                  "ws_request"
+                ],
+                "properties": {
+                  "action": {
+                    "const": "obs_ws"
+                  }
+                }
+              }
+            ]
+          }
+        ],
+        "options": {
+          "switcher": false
+        }
+      }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "ScheduleType": {
+      "description": "The type of schedule for an event.",
+      "type": "string",
+      "enum": [
+        "date",
+        "recurring"
+      ],
+      "options": {
+        "enum_titles": [
+          "Specific Date/Time",
+          "Recurring Event"
+        ]
+      }
+    },
+    "EventAction": {
+      "description": "An action to trigger in OBS.",
+      "type": "string",
+      "enum": [
+        "start_stream",
+        "stop_stream",
+        "start_recording",
+        "pause_recording",
+        "stop_recording",
+        "advanced_scene_switcher",
+        "obs_ws"
+      ],
+      "options": {
+        "enum_titles": [
+          "Start Stream",
+          "Stop Stream",
+          "Start Recording",
+          "Pause Recording",
+          "Stop Recording",
+          "Advanced Scene Switcher",
+          "Raw Websocket"
+        ]
+      }
+    },
+    "OBSWSRequest": {
+      "description": "A message to send to OBS as a raw Websocket message.",
+      "type": "object",
+      "required": [
+        "type",
+        "data"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "data": {
+          "type": "object"
+        }
+      },
+      "options": {
+        "dependencies": {
+          "action": "obs_ws"
+        }
+      }
+    }
+  }
+}

package/dist/config.js

@@ -0,0 +1,53 @@
+import { DateTime } from "luxon";
+
+/** @typedef {'date'|'recurring'} ConfigEventType */
+
+/**
+ * @typedef {'start_stream'|'stop_stream'|'start_recording'|'pause_recording'|'stop_recording'|'advanced_scene_switcher'|'obs_ws'} ConfigEventAction
+ */
+
+/**
+ * @typedef {Object} OBSWSRequest
+ * @property {string} type
+ * @property {Object} data
+ */
+
+/**
+ * @typedef {Object} ConfigEvent
+ * @property {string} [name]
+ * @property {boolean} [enabled=true]
+ * @property {ConfigEventType} schedule_type
+ * @property {string} [date] Only present if `schedule_type` is `'date'`.
+ * @property {string} [schedule] Only present if `schedule_type` is `'recurring'`.
+ * @property {ConfigEventAction} action
+ * @property {string} [switcher_message] Only present if `action` is `'advanced_scene_switcher'`.
+ * @property {OBSWSRequest} [ws_request] Only present if `action` is `'obs_ws'`.
+ */
+
+/**
+ * @typedef {Object} Config
+ * @property {ConfigEvent[]} events
+ */
+
+/**
+ * 
+ * @param {DateTime} date 
+ * @param {ConfigEvent} event 
+ * @returns {boolean}
+ */
+export function checkEventSchedule(date, event) {
+    if (event.enabled == false) {
+        return false;
+    }
+
+    if (event.date) {
+        const eventDate = DateTime.fromISO(event.date);
+        // console.log(eventDate.getTime(), date.getTime())
+        return eventDate.startOf('second').toMillis() == date.toMillis();
+    } else if (event.schedule) {
+        // TODO: match `schedule` field
+        return false;
+    } else {
+        return false;
+    }
+}

package/dist/index.js

@@ -0,0 +1,64 @@
+import * as fs from 'node:fs';
+import { setInterval } from 'node:timers/promises';
+
+import { checkEventSchedule } from './config.js';
+import { convertEventToWebsocketRequest } from './obs.js';
+
+import { OBSWebSocket } from "obs-websocket-js";
+import { DateTime } from 'luxon';
+
+/** @typedef {import('./config.js').Config} Config */
+
+/**
+ * @this {import("commander").Command}
+ */
+export async function run() {
+    const {
+        ipAddress,
+        password,
+        config: configPath
+    } = this.opts();
+
+    // Connect to OBS-WS
+    const obs = new OBSWebSocket();
+
+    try {
+        await obs.connect(
+            ipAddress ? `ws://${ipAddress}` : undefined,
+            password,
+        );
+    } catch (error) {
+        console.error('Failed to connect to OBS.', error.code, error.message);
+        process.exit(1);
+    }
+
+    /** @type {Config} */
+    let config = {};
+
+    function updateConfigFromFile() {
+        const fileContents = fs.readFileSync(configPath, "utf8")
+            .replace(/^[ \t]*\/\/.+$\n/gm, '');
+        config = JSON.parse(fileContents);
+    }
+
+    // Read config file for initial value
+    updateConfigFromFile();
+
+    // Watch config file for changes
+    fs.watchFile(configPath, { interval: 1000 }, updateConfigFromFile);
+
+    // Forever, every second, check if current time matches an event in the config
+    for await (const start of setInterval(1000, Date.now())) {
+        const date = DateTime.now().startOf('second');
+
+        const matchingEvents = config.events
+            .filter(e => checkEventSchedule(date, e));
+
+        const wsRequests = matchingEvents
+            .flatMap(convertEventToWebsocketRequest);
+
+        await obs.callBatch(wsRequests, {
+            haltOnFailure: false,
+        });
+    }
+}

package/dist/obs.js

@@ -0,0 +1,64 @@
+/** @typedef {import('./config.js').ConfigEvent} ConfigEvent */
+
+/**
+ * Maps a `ConfigEvent` to an OBS Websocket request.
+ * @param {ConfigEvent} event 
+ * @returns {import("obs-websocket-js").RequestBatchRequest[]}
+ */
+export function convertEventToWebsocketRequest(event) {
+    const requestID = `${event.name ? event.name + '.' : ''}${event.action}`;
+
+    switch (event.action) {
+        case "start_stream":
+            return [{
+                requestID,
+                requestType: 'StartStream',
+            }];
+        case "stop_stream":
+            return [{
+                requestID,
+                requestType: 'StopStream',
+            }];
+        case "start_recording":
+            return [{
+                requestID,
+                requestType: 'StartRecord',
+            }];
+        case "pause_recording":
+            return [{
+                requestID,
+                requestType: 'PauseRecord',
+            }];
+        case "stop_recording":
+            return [{
+                requestID,
+                requestType: 'StopRecord',
+            }];
+        case "advanced_scene_switcher":
+            if (event.switcher_message) {
+                return [{
+                    requestID,
+                    requestType: 'CallVendorRequest',
+                    requestData: {
+                        requestData: {
+                            message: event.switcher_message,
+                        },
+                        requestType: "AdvancedSceneSwitcherMessage",
+                        vendorName: "AdvancedSceneSwitcher",
+                    },
+                }];
+            } else {
+                return [];
+            }
+        case "obs_ws":
+            if (event.ws_request) {
+                return [{
+                    requestID,
+                    requestType: event.ws_request.type,
+                    requestData: event.ws_request.data,
+                }];
+            } else {
+                return [];
+            }
+    }
+}

package/examples/config-example.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "../config-schema.json",
+  "events": [
+    {
+      "name": "Example Event 1",
+      "schedule_type": "date",
+      "date": "2026-01-06T10:59",
+      "action": "start_recording"
+    },
+    {
+      "name": "Example Event 2",
+      "schedule_type": "recurring",
+      "schedule": "",
+      "action": "start_recording"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "obs-scheduler",
+  "version": "0.0.1",
+  "description": "A CLI tool for scheduling OBS functionality.",
+  "author": "edonv",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edonv/obs-scheduler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/edonv/obs-scheduler/issues"
+  },
+  "homepage": "https://github.com/edonv/obs-scheduler#readme",
+  "dependencies": {
+    "commander": "^14.0.2",
+    "luxon": "^3.7.2",
+    "obs-websocket-js": "^5.0.7"
+  },
+  "bin": {
+    "obs-scheduler": "cli.js"
+  }
+}