obs-studio-node: calling libOBS from Node and Electron

libOBS as a library, not as a running application

The library's purpose is stated in the first line of the README: it intends to provide bindings to obs-studio's internal library, named libobs accordingly, for the purpose of using it from a node runtime. The consequence of that framing is the whole design. This is not a remote control for an OBS instance somebody else launched. It is a way to link the OBS internals into your own process and call them. The topics list makes the same point with c, cmake, cpp, electron, javascript, node, node-module, nodejs, obs, obs-studio and typescript, and the primary language is recorded as C++ with a TypeScript surface on top. The package on npm is @streamlabs/obs-studio-node, published by Streamlabs, and the manifest describes it as experimental bindings to obs-studio using nan directly, which tells you the binding layer predates the current native module approaches. Currently, only Windows and MacOS are supported, and the default branch of the repository is staging rather than master, which tells you how the project is developed.

The build needs Git, Node, Yarn and CMake, plus a platform toolchain

The prerequisites are Git, Node.js, Yarn and CMake, and on Windows you also need Visual Studio 2019 or 2022 along with the Windows SDK, which may be installed by the Visual Studio 2022 installer. On Mac, building requires Xcode. That is a heavier toolchain than an npm install, and the reason is structural: the module contains native code and an OBS source tree, so it has to be compiled. The README explains the build script choice: it uses a flexible cmake script to be as broad and generic as possible in order to prevent the need to constantly manage the cmake script for custom uses, while also providing sane defaults, and it follows a pretty standard cmake layout that you may execute however you want. The repository layout supports that story, with CMakeLists.txt at the root, a cmake directory, a ci directory, a js directory holding the TypeScript surface, source and tools directories, plus obs-studio-client and obs-studio-server directories and a lib-streamlabs-ipc directory, and a .gitmodules file at the root for the submodules the build pulls in.

The Windows build sequence

The example build is a five-step sequence that works for most people who want a local build. You install the JavaScript dependencies and pull the submodules, create a build directory, configure CMake with a generator and an architecture, and then build and install:

yarn install
git submodule update --init --recursive
mkdir build
cd build
cmake .. -G"Visual Studio 17 2022" -A x64 -DCMAKE_PREFIX_PATH=%CD%/libobs-src/cmake/
cmake --build . --target install --config RelWithDebInfo

The README explains what that does: it will download any required dependencies, build the module, and then place it in an archive compatible with npm or yarn that you may specify in a given package.json. The CMAKE_PREFIX_PATH pointing at the libobs-src/cmake directory is the piece that ties the build to the bundled OBS source rather than a system install. There is also a variant for people testing a local libobs development package that was built before it bundled its public development dependencies, where you pass the dependency package prefixes through OSN_LIBOBS_DEPENDENCY_PREFIX_PATH:

cmake .. -G"Visual Studio 17 2022" -A x64 -DCMAKE_PREFIX_PATH=%CD%/libobs-src/cmake/ -DOSN_LIBOBS_DEPENDENCY_PREFIX_PATH=D:/path/to/obs/.deps/obs-deps-2025-08-23sl2-x64

That flag is what a contributor working against an in-development OBS build would need, and the example path shows the shape of the dependency directory an OBS source build produces.

The Mac build, and the codesigning gotcha it creates

The Mac sequence mirrors the Windows one, with two differences that matter. The install prefix points into a node_modules path inside the desktop repository, and the architecture is set to arm64 explicitly:

yarn install
git submodule update --init --recursive
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/Users/<you>/streamlabs/desktop/node_modules/obs-studio-node/OSN.app/distribute/obs-studio-node -DCMAKE_OSX_ARCHITECTURES=arm64 -G Xcode
cmake --build . --target install --config RelWithDebInfo

The example assumes the desktop repo is also installed in the same parent folder and attempts to build a test developer app bundle so you can see browser sources and similar. The README then names the only gotcha, and it is a specific one. If you later run the yarn package:mac-arm64 command in the desktop folder instead, you should remove OSN.app from the CMAKE_INSTALL_PREFIX path, because the electron-builder scripts throw an error saying it is not a fully formed app bundle during codesign. In other words, a development build and a packaged build want different install prefixes, and confusing them breaks signing rather than the build.

A custom OBS build has three configuration requirements

By default the build downloads a pre-built version of libobs if none is specified, and the README says that this pre-built version may not be what you want to use, or maybe you are testing a new OBS feature. You can specify a custom archive of your own, but some changes need to be made to obs-studio's default configuration before building. ENABLE_SCRIPTING must be set to false, ENABLE_UI must be set to false, and QTDIR should not be specified as it is not used. Those three constraints exist for a reason that follows from the architecture: a headless libOBS with no Qt user interface and no scripting runtime is a library that can be embedded, and a library that drags in a Qt event loop and a script host cannot be. The README links the obs-studio wiki install instructions for anyone who does not know how to build OBS Studio from source, which is a reasonable admission that this is a two-project build rather than a one-project build.

Static analysis targets that most projects skip

Two static analysis workflows are documented in detail, and they say something about the project's engineering culture. For cppcheck, the README says to install cppcheck and add its folder to PATH, and the check is run from the command line with a dedicated CMake target, or built from Visual Studio, with the report output format set as compatible and navigation to file:line possible from the build results panel. Some warnings are suppressed in files named obs-studio-client/cppcheck_suppressions_list.txt and obs-studio-server/cppcheck_suppressions_list.txt, which tells you the suppression list is versioned alongside the code. The Clang Analyzer setup is longer. Ninja and LLVM have to be installed, with a warning that depot_tool has broken ninja, and the README opens cmd.exe to set up the environment, using clang-cl as the compiler and ccc-analyzer.bat as the analyzer driver:

mkdir build_clang
cd build_clang

set CCC_CC=clang-cl
set CCC_CXX=clang-cl
set CC=ccc-analyzer.bat
set CXX=c++-analyzer.bat

cmake  -G "Ninja" -DCLANG_ANALYZE_CONFIG=1 -DCMAKE_INSTALL_PREFIX:PATH=""  -DCMAKE_LINKER=lld-link -DCMAKE_BUILD_TYPE="Debug"   -DCMAKE_SYSTEM_NAME="Generic" -DCMAKE_MAKE_PROGRAM=ninja.exe ..

The README adds that the step with fixing errors is important, because the code base and especially the third-party code are not ready to be built with clang, and that files which failed to compile will not be scanned for errors. A scan over a tree that does not compile is a scan of a subset, and the project is candid about that.

The TypeScript surface is generated, and CI checks it

The modern part of the repository is a small convention that removes a class of bug. js/module.ts is the source of truth, and js/module.js plus js/module.d.ts and the index and type_check siblings are tsc outputs of js/tsconfig.json. Because the npm package ships them as-is, they are committed to the repository. You regenerate them with yarn build:javascript, and yarn local:build already chains that step. CI rejects stale outputs via .github/workflows/check-js-generated.yml, with the check script at ci/check-js-generated.sh. For a native module where the JavaScript layer is generated from a single file, a stale committed artefact is a genuine hazard, because the C++ side can change while the shipped type definitions do not, and the check closes that gap automatically. The test story is similar in spirit. The tests are written in TypeScript and use Mocha as the test framework, with electron-mocha to make Mocha run inside Electron, and Chai as the assertion framework.

Running the tests, and the environment they need

Building is a prerequisite for testing, and the tests need to know where you built it. You can build it any way you want, but you must use CMAKE_INSTALL_PREFIX to install obs-studio-node in a folder of your choosing, because the tests use that variable to know where the module is. There is a further wrinkle, because the project uses its own fork of Electron, so you also need to create an environment variable called ELECTRON_PATH pointing at the Electron binary in the node_modules folder after running yarn install. The README then offers three ways to build. The terminal route in the obs-studio-node root folder is yarn install, then git submodule update --init --recursive --force, then mkdir build, then a cmake configure with the install prefix set, then cmake --build build --target install. The package.json scripts route is mkdir build, yarn local:config, yarn local:build, with yarn local:clean available to repeat steps two to three. The third route is the CMake GUI, where you point it at the source and build directories, click Configure, change CMAKE_INSTALL_PREFIX, click Generate and then build in Visual Studio. The manifest shows the test scripts as well, with test:unit running a script in the ci directory, test:integration invoking electron-mocha with a timeout of 80000 and the js-flags for garbage collection, and test:ci adding two retries.

Editorial conclusion

obs-studio-node suits a team building an Electron-based streaming tool that needs to drive OBS programmatically, since embedding libOBS as a library is a different proposition from scripting OBS with Lua or controlling it over a websocket. It is the wrong tool if you want to control an already-running OBS instance from another process, because the design is a library you link and build, and it is the wrong tool if you are not prepared to maintain a C++ and CMake build, since the npm package ships prebuilt artefacts but a custom build means handling the OBS submodule and toolchain yourself. Verify first that the OBS Studio version you need is present in the bundled libobs-src submodule, that the platform you target is one of the two the README names, and note that the newest tagged release is v0.4.26 from 2019 while the package manifest sits at 0.3.99 on a staging branch with the last push on 2026-10-19.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. streamlabs/obs-studio-node on GitHub