@zeke/obsx 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# obsx
+
+A CLI for [OBS](https://obsproject.com/).
+
+## Install
+
+Run without installing:
+
+```sh
+npx zeke/obsx <command>
+```
+
+Install globally:
+
+```sh
+npm install -g zeke/obsx
+obsx <command>
+```
+
+## Usage
+
+This CLI connects to OBS via the built-in obs-websocket server (protocol v5).
+
+- OBS: OBS 28+ (or obs-websocket 5.x installed)
+- WebSocket server: enabled in OBS
+- Default URL: `ws://localhost:4455`
+- Authentication: none by default
+
+In OBS, look for `Tools -> WebSocket Server Settings` (or similar) and set the port to `4455`.
+
+Connection config is optional; by default it uses `ws://localhost:4455` with no password.
+
+To override, set environment variables:
+
+- `OBSX_URL` (default: `ws://localhost:4455`)
+- `OBSX_PASSWORD` (optional)
+
+Add a webcam source to the current scene:
+
+```sh
+obsx add-webcam
+```
+
+Or without installing:
+
+```sh
+npx zeke/obsx add-webcam
+```
+
+Interactive mode (hit enter to accept defaults):
+
+```sh
+obsx add-webcam --interactive
+```
+
+Add image sources for all images in the current directory (skips ones already in the scene):
+
+```sh
+obsx add-images
+```
+
+Use a specific directory:
+
+```sh
+obsx add-images --dir "$PWD"
+```

package/bin/obsx.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { addImages } from "./commands/add-images.js";
+import { addWebcam } from "./commands/add-webcam.js";
+function printHelp() {
+    console.log(`obsx - A CLI for OBS
+
+Usage:
+  obsx <command> [options]
+
+Environment:
+  OBSX_URL       OBS websocket URL (default: ws://localhost:4455)
+  OBSX_PASSWORD  OBS websocket password (optional)
+
+Commands:
+  add-images   Add image sources for images in a directory (default: cwd)
+  add-webcam   Add a webcam input to the current scene
+
+Examples:
+  npx zeke/obsx add-images
+  npx zeke/obsx add-images --dir /path/to/images
+  npx zeke/obsx add-webcam --interactive
+`);
+}
+async function run(argv) {
+    const [maybeCommand, ...rest] = argv;
+    if (!maybeCommand || maybeCommand === "-h" || maybeCommand === "--help") {
+        printHelp();
+        return;
+    }
+    const command = maybeCommand;
+    if (command === "add-images") {
+        await addImages(rest);
+        return;
+    }
+    if (command === "add-webcam") {
+        await addWebcam(rest);
+        return;
+    }
+    console.error(`Unknown command: ${maybeCommand}`);
+    printHelp();
+    process.exitCode = 1;
+}
+run(process.argv.slice(2)).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/commands/add-images.js

@@ -0,0 +1,205 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import process from "node:process";
+import { getObsConnectionOptionsFromEnv, withOBS } from "../lib/obs.js";
+const IMAGE_EXTS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".bmp",
+    ".tif",
+    ".tiff",
+    ".webp",
+]);
+function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i] ?? "";
+        const next = argv[i + 1];
+        if (arg === "--scene" && typeof next === "string") {
+            out.scene = next;
+            i += 1;
+            continue;
+        }
+        if (arg === "--dir" && typeof next === "string") {
+            out.dir = next;
+            i += 1;
+            continue;
+        }
+    }
+    return out;
+}
+function mergeOptions(overrides, cwd) {
+    return {
+        scene: overrides.scene,
+        dir: overrides.dir ?? cwd,
+    };
+}
+function expandHome(p) {
+    if (!p.startsWith("~/"))
+        return p;
+    return path.join(os.homedir(), p.slice(2));
+}
+function normalizeFilePath(p) {
+    const expanded = expandHome(p);
+    const resolved = path.resolve(expanded);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+function listImagesInDir(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isFile())
+        .map((e) => e.name)
+        .filter((name) => IMAGE_EXTS.has(path.extname(name).toLowerCase()))
+        .sort((a, b) => a.localeCompare(b))
+        .map((fileName) => ({
+        fileName,
+        filePath: normalizeFilePath(path.join(dir, fileName)),
+    }));
+}
+async function pickImageInputKind(obs) {
+    const list = await obs.call("GetInputKindList");
+    const kinds = list.inputKinds ?? [];
+    if (kinds.includes("image_source"))
+        return "image_source";
+    const imageKind = kinds.find((k) => k.toLowerCase().includes("image"));
+    if (imageKind)
+        return imageKind;
+    throw new Error(`No image input kind found. Available: ${kinds.join(", ")}`);
+}
+async function getSceneItemSourceNames(obs, sceneName) {
+    const res = await obs.call("GetSceneItemList", { sceneName });
+    const items = (res.sceneItems ?? []);
+    const names = items
+        .map((item) => {
+        const anyItem = item;
+        return String(anyItem.sourceName ?? "");
+    })
+        .filter((n) => n.length);
+    return [...new Set(names)];
+}
+async function getExistingImageFilesBySourceName(obs, sourceNames) {
+    const out = new Map();
+    for (const sourceName of sourceNames) {
+        try {
+            const settings = await obs.call("GetInputSettings", { inputName: sourceName });
+            const file = settings.inputSettings?.file;
+            if (typeof file === "string" && file.trim().length) {
+                out.set(sourceName, normalizeFilePath(file));
+            }
+        }
+        catch {
+            // Not an input with settings (e.g. a nested scene). Ignore.
+        }
+    }
+    return out;
+}
+function computeFitTransform(canvasW, canvasH) {
+    return {
+        positionX: canvasW / 2,
+        positionY: canvasH / 2,
+        alignment: 0,
+        boundsType: "OBS_BOUNDS_SCALE_INNER",
+        boundsAlignment: 0,
+        boundsWidth: canvasW,
+        boundsHeight: canvasH,
+    };
+}
+export async function addImages(argv, cwd = process.cwd()) {
+    const options = mergeOptions(parseArgs(argv), cwd);
+    const dir = normalizeFilePath(options.dir);
+    const images = listImagesInDir(dir);
+    if (!images.length) {
+        console.log(`No images found in: ${dir}`);
+        return;
+    }
+    await withOBS(getObsConnectionOptionsFromEnv(), async (obs) => {
+        const currentScene = await obs.call("GetCurrentProgramScene");
+        const sceneName = options.scene ?? currentScene.currentProgramSceneName;
+        const [video, inputKind, sourceNames, inputList] = await Promise.all([
+            obs.call("GetVideoSettings"),
+            pickImageInputKind(obs),
+            getSceneItemSourceNames(obs, sceneName),
+            obs.call("GetInputList"),
+        ]);
+        const canvasW = video.baseWidth;
+        const canvasH = video.baseHeight;
+        const existingNames = new Set(sourceNames);
+        const allInputNames = new Set((inputList.inputs ?? []).map((i) => i.inputName));
+        const existingFilesBySourceName = await getExistingImageFilesBySourceName(obs, sourceNames);
+        const existingFiles = new Set(existingFilesBySourceName.values());
+        let created = 0;
+        let skipped = 0;
+        for (const img of images) {
+            const inputName = img.fileName;
+            if (existingNames.has(inputName)) {
+                skipped += 1;
+                continue;
+            }
+            if (existingFiles.has(img.filePath)) {
+                skipped += 1;
+                continue;
+            }
+            if (allInputNames.has(inputName)) {
+                let existingInputFile;
+                try {
+                    const settings = await obs.call("GetInputSettings", { inputName });
+                    const file = settings.inputSettings?.file;
+                    if (typeof file === "string" && file.trim().length) {
+                        existingInputFile = normalizeFilePath(file);
+                    }
+                }
+                catch {
+                    existingInputFile = undefined;
+                }
+                if (!existingInputFile || existingInputFile !== img.filePath) {
+                    console.log(`Skipping ${img.fileName}: OBS input name already exists with a different file (${inputName})`);
+                    skipped += 1;
+                    continue;
+                }
+                const sceneItem = await obs.call("CreateSceneItem", {
+                    sceneName,
+                    sourceName: inputName,
+                    sceneItemEnabled: true,
+                });
+                await obs.call("SetSceneItemTransform", {
+                    sceneName,
+                    sceneItemId: sceneItem.sceneItemId,
+                    sceneItemTransform: computeFitTransform(canvasW, canvasH),
+                });
+                existingNames.add(inputName);
+                existingFiles.add(img.filePath);
+                created += 1;
+                continue;
+            }
+            const createdInput = await obs.call("CreateInput", {
+                sceneName,
+                inputName,
+                inputKind,
+                inputSettings: {
+                    file: img.filePath,
+                },
+                sceneItemEnabled: true,
+            });
+            await obs.call("SetSceneItemTransform", {
+                sceneName,
+                sceneItemId: createdInput.sceneItemId,
+                sceneItemTransform: computeFitTransform(canvasW, canvasH),
+            });
+            existingNames.add(inputName);
+            existingFiles.add(img.filePath);
+            created += 1;
+        }
+        console.log(`Scene: ${sceneName}`);
+        console.log(`Dir: ${dir}`);
+        console.log(`Created: ${created}`);
+        console.log(`Skipped: ${skipped}`);
+    });
+}

package/dist/commands/add-webcam.js

@@ -0,0 +1,341 @@
+import { createInterface } from "node:readline/promises";
+import process from "node:process";
+import { getObsConnectionOptionsFromEnv, withOBS } from "../lib/obs.js";
+const DEFAULTS = {
+    interactive: false,
+    baseName: "Video Capture Device",
+    inputKind: undefined,
+    deviceSelection: undefined,
+    addChromaKey: true,
+    addColorCorrection: true,
+    saturation: -1.0,
+    contrast: 0.7,
+};
+const DEVICE_PRIORITY = ["iphone camera", "studio display camera", "facetime hd camera"];
+const INPUT_KIND_PREFERENCE = [
+    "av_capture_input",
+    "macos-avcapture",
+    "avf_capture_input",
+    "avfoundation_input",
+    "video_capture_device",
+];
+function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i] ?? "";
+        const next = argv[i + 1];
+        if (arg === "-i" || arg === "--interactive") {
+            out.interactive = true;
+            continue;
+        }
+        if (arg === "--base-name" && typeof next === "string") {
+            out.baseName = next;
+            i += 1;
+            continue;
+        }
+        if (arg === "--input-kind" && typeof next === "string") {
+            out.inputKind = next;
+            i += 1;
+            continue;
+        }
+        if (arg === "--device" && typeof next === "string") {
+            out.deviceSelection = next;
+            i += 1;
+            continue;
+        }
+        if (arg === "--no-chroma-key") {
+            out.addChromaKey = false;
+            continue;
+        }
+        if (arg === "--no-color-correction") {
+            out.addColorCorrection = false;
+            continue;
+        }
+        if (arg === "--saturation" && typeof next === "string") {
+            out.saturation = Number(next);
+            i += 1;
+            continue;
+        }
+        if (arg === "--contrast" && typeof next === "string") {
+            out.contrast = Number(next);
+            i += 1;
+            continue;
+        }
+    }
+    return out;
+}
+function mergeOptions(overrides) {
+    return {
+        ...DEFAULTS,
+        ...overrides,
+    };
+}
+async function ask(rl, question, defaultValue) {
+    const suffix = defaultValue.length ? ` [${defaultValue}]` : "";
+    const answer = (await rl.question(`${question}${suffix}: `)).trim();
+    return answer.length ? answer : defaultValue;
+}
+async function askYesNo(rl, question, defaultValue) {
+    const prompt = defaultValue ? "[Y/n]" : "[y/N]";
+    const answer = (await rl.question(`${question} ${prompt}: `)).trim().toLowerCase();
+    if (!answer)
+        return defaultValue;
+    if (["y", "yes"].includes(answer))
+        return true;
+    if (["n", "no"].includes(answer))
+        return false;
+    return defaultValue;
+}
+function pickDefaultIndexFromNeedles(labels, needles) {
+    for (const needle of needles) {
+        const idx = labels.findIndex((l) => l.toLowerCase().includes(needle));
+        if (idx !== -1)
+            return idx;
+    }
+    return 0;
+}
+async function askChoice(rl, question, choices, defaultIndex) {
+    console.log("\n" + question);
+    for (let i = 0; i < choices.length; i += 1) {
+        const n = String(i + 1).padStart(2, " ");
+        console.log(`  ${n}) ${choices[i].label}`);
+    }
+    const defaultHuman = String(defaultIndex + 1);
+    const answer = (await rl.question(`Select [${defaultHuman}]: `)).trim();
+    if (!answer)
+        return choices[defaultIndex].value;
+    const num = Number(answer);
+    if (Number.isInteger(num) && num >= 1 && num <= choices.length) {
+        return choices[num - 1].value;
+    }
+    const exact = choices.find((c) => c.value === answer) ?? choices.find((c) => c.label === answer);
+    if (exact)
+        return exact.value;
+    return choices[defaultIndex].value;
+}
+async function pickInputKind(obs) {
+    const list = await obs.call("GetInputKindList");
+    const kinds = list.inputKinds ?? [];
+    for (const preferred of INPUT_KIND_PREFERENCE) {
+        if (kinds.includes(preferred))
+            return preferred;
+    }
+    const captureKind = kinds.find((kind) => kind.toLowerCase().includes("capture"));
+    if (captureKind)
+        return captureKind;
+    throw new Error(`No supported capture input kinds found: ${kinds.join(", ")}`);
+}
+async function uniqueInputName(obs, baseName) {
+    const list = await obs.call("GetInputList");
+    const names = new Set(list.inputs.map((input) => input.inputName));
+    if (!names.has(baseName))
+        return baseName;
+    let suffix = 2;
+    while (names.has(`${baseName}-${suffix}`))
+        suffix += 1;
+    return `${baseName}-${suffix}`;
+}
+async function getDeviceChoices(obs, inputName) {
+    const propertyCandidates = [
+        "device_id",
+        "device",
+        "device_name",
+        "video_device",
+        "source",
+        "input",
+    ];
+    for (const propertyName of propertyCandidates) {
+        try {
+            const props = await obs.call("GetInputPropertiesListPropertyItems", {
+                inputName,
+                propertyName,
+            });
+            const items = props.propertyItems ?? [];
+            const choices = items
+                .map((item) => ({
+                propertyName,
+                itemName: String(item.itemName ?? ""),
+                itemValue: String(item.itemValue ?? ""),
+            }))
+                .filter((c) => c.itemName.length || c.itemValue.length);
+            if (choices.length)
+                return choices;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!message.includes("Unable to find a property"))
+                throw err;
+        }
+    }
+    const settings = await obs.call("GetInputSettings", { inputName });
+    const settingKeys = Object.keys(settings.inputSettings ?? {});
+    console.log("Available input settings keys:", settingKeys);
+    return [];
+}
+function pickDeviceDefaultIndex(choices) {
+    const labels = choices.map((c) => c.itemName);
+    return pickDefaultIndexFromNeedles(labels, DEVICE_PRIORITY);
+}
+function findDeviceIndexBySelection(choices, selection) {
+    const needle = selection.trim().toLowerCase();
+    if (!needle)
+        return -1;
+    return choices.findIndex((c) => `${c.itemName} ${c.itemValue} ${c.propertyName}`.toLowerCase().includes(needle));
+}
+async function resolveOptionsInteractive(initial) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("Interactive mode requires a TTY.");
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const baseName = await ask(rl, "Base source name", initial.baseName);
+        const addChromaKey = await askYesNo(rl, "Add Chroma Key filter?", initial.addChromaKey);
+        const addColorCorrection = await askYesNo(rl, "Add Color Correction filter?", initial.addColorCorrection);
+        let saturation = initial.saturation;
+        let contrast = initial.contrast;
+        if (addColorCorrection) {
+            const satRaw = await ask(rl, "Color Correction: saturation", String(initial.saturation));
+            const conRaw = await ask(rl, "Color Correction: contrast", String(initial.contrast));
+            saturation = Number(satRaw);
+            contrast = Number(conRaw);
+        }
+        return {
+            ...initial,
+            baseName,
+            addChromaKey,
+            addColorCorrection,
+            saturation,
+            contrast,
+        };
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function addWebcam(argv) {
+    const argOverrides = parseArgs(argv);
+    let options = mergeOptions(argOverrides);
+    if (options.interactive) {
+        options = await resolveOptionsInteractive(options);
+    }
+    if (!Number.isFinite(options.saturation)) {
+        throw new Error(`Invalid --saturation: ${options.saturation}`);
+    }
+    if (!Number.isFinite(options.contrast)) {
+        throw new Error(`Invalid --contrast: ${options.contrast}`);
+    }
+    await withOBS(getObsConnectionOptionsFromEnv(), async (obs) => {
+        const currentScene = await obs.call("GetCurrentProgramScene");
+        const sceneName = currentScene.currentProgramSceneName;
+        let inputKind = options.inputKind;
+        if (!inputKind)
+            inputKind = await pickInputKind(obs);
+        if (options.interactive) {
+            const list = await obs.call("GetInputKindList");
+            const kinds = list.inputKinds ?? [];
+            const preferredDefault = kinds.includes(inputKind) ? inputKind : await pickInputKind(obs);
+            const captureKinds = kinds
+                .filter((k) => k.toLowerCase().includes("capture") || INPUT_KIND_PREFERENCE.includes(k))
+                .sort((a, b) => {
+                const ai = INPUT_KIND_PREFERENCE.indexOf(a);
+                const bi = INPUT_KIND_PREFERENCE.indexOf(b);
+                if (ai === -1 && bi === -1)
+                    return a.localeCompare(b);
+                if (ai === -1)
+                    return 1;
+                if (bi === -1)
+                    return -1;
+                return ai - bi;
+            });
+            const choices = (captureKinds.length ? captureKinds : kinds).map((k) => ({
+                label: k,
+                value: k,
+            }));
+            const defaultIndex = Math.max(0, choices.findIndex((c) => c.value === preferredDefault));
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                inputKind = await askChoice(rl, "Input kind", choices, defaultIndex);
+            }
+            finally {
+                rl.close();
+            }
+        }
+        const inputName = await uniqueInputName(obs, options.baseName);
+        await obs.call("CreateInput", {
+            sceneName,
+            inputName,
+            inputKind,
+            inputSettings: {},
+            sceneItemEnabled: true,
+        });
+        const deviceChoices = await getDeviceChoices(obs, inputName);
+        if (!deviceChoices.length) {
+            throw new Error(`No capture devices found for ${inputKind}.`);
+        }
+        let deviceIndex = pickDeviceDefaultIndex(deviceChoices);
+        if (options.deviceSelection) {
+            const idx = findDeviceIndexBySelection(deviceChoices, options.deviceSelection);
+            if (idx !== -1)
+                deviceIndex = idx;
+        }
+        if (options.interactive) {
+            const labels = deviceChoices.map((c) => `${c.itemName} (${c.propertyName})`);
+            const defaultIndex = pickDefaultIndexFromNeedles(labels, DEVICE_PRIORITY);
+            const choices = deviceChoices.map((c) => ({
+                label: `${c.itemName} (${c.propertyName})`,
+                value: `${c.propertyName}::${c.itemValue}`,
+            }));
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                const picked = await askChoice(rl, "Device", choices, defaultIndex);
+                const [propertyName, itemValue] = picked.split("::");
+                const idx = deviceChoices.findIndex((c) => c.propertyName === propertyName && c.itemValue === itemValue);
+                if (idx !== -1)
+                    deviceIndex = idx;
+            }
+            finally {
+                rl.close();
+            }
+        }
+        const device = deviceChoices[deviceIndex];
+        await obs.call("SetInputSettings", {
+            inputName,
+            inputSettings: {
+                [device.propertyName]: device.itemValue,
+            },
+            overlay: true,
+        });
+        if (options.addChromaKey) {
+            await obs.call("CreateSourceFilter", {
+                sourceName: inputName,
+                filterName: "Chroma Key",
+                filterKind: "chroma_key_filter",
+                filterSettings: {},
+            });
+        }
+        if (options.addColorCorrection) {
+            await obs.call("CreateSourceFilter", {
+                sourceName: inputName,
+                filterName: "Color Correction",
+                filterKind: "color_filter",
+                filterSettings: {
+                    saturation: options.saturation,
+                    contrast: options.contrast,
+                },
+            });
+        }
+        const filters = await obs.call("GetSourceFilterList", {
+            sourceName: inputName,
+        });
+        const filterSummaries = filters.filters.map((filter) => ({
+            name: filter.filterName,
+            kind: filter.filterKind,
+            enabled: filter.filterEnabled,
+        }));
+        console.log("Filters:", filterSummaries);
+        console.log("Created input:", inputName);
+        console.log("Scene:", sceneName);
+        console.log("Input kind:", inputKind);
+        console.log("Device:", device.itemName);
+    });
+}

package/dist/lib/obs.js

@@ -0,0 +1,26 @@
+import OBSWebSocket from "obs-websocket-js";
+import process from "node:process";
+export const DEFAULT_OBS_URL = "ws://localhost:4455";
+export function getObsConnectionOptionsFromEnv() {
+    const url = (process.env.OBSX_URL ?? "").trim() || DEFAULT_OBS_URL;
+    const passwordRaw = (process.env.OBSX_PASSWORD ?? "").trim();
+    return {
+        url,
+        password: passwordRaw.length ? passwordRaw : undefined,
+    };
+}
+export async function withOBS(options, fn) {
+    const obs = new OBSWebSocket();
+    await obs.connect(options.url, options.password);
+    try {
+        return await fn(obs);
+    }
+    finally {
+        try {
+            await obs.disconnect();
+        }
+        catch {
+            // ignore disconnect errors
+        }
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@zeke/obsx",
+  "description": "A CLI for OBS",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "obsx": "./bin/obsx.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "node ./node_modules/typescript/bin/tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "obs-websocket-js": "^5.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "@eslint/js": "^9.20.0",
+    "eslint": "^9.20.1",
+    "tsx": "^4.19.1",
+    "typescript": "^5.4.2",
+    "typescript-eslint": "^8.24.1"
+  }
+}