obs-streamer-tools-plugin/README.md

# obs-streamer-tools-plugin

Native OBS Studio source plugin that will pull streamer-tools camera feeds
directly from LiveKit over WebRTC (via LiveKit's `livekit-ffi`), replacing
the current SRT/RTSP-via-VLC-or-Media-Source path for directors. Full
design: `docs/superpowers/specs/2026-09-06-obs-camera-plugin-design.md` in
the `streamer-tools` repo (as of this writing, that doc lives on the
`worktree-obs-plugin-server-api` branch there, not yet merged to `main`).

## Status: scaffolding only

**This repository does not talk to LiveKit or streamer-tools yet.** This
first pass exists to prove the CMake toolchain, the core-library/OBS-adapter
split, and the three-platform Gitea Actions CI pipeline all actually work,
so the next phase (real `livekit-ffi` integration) can be planned against
verified facts instead of assumptions. See the design doc's "Components"
and "CI / build pipeline" sections for the target architecture this scaffold
is standing up.

## Layout

```
core/           - core library (C++17, no OBS dependency, headless-testable)
  include/stplugin/
    core.h        C++ API (ConnectionConfig, core_version())
    core_c.h       C ABI wrapper the OBS adapter calls into
  src/core.cpp
  tests/           dependency-free CTest unit tests

obs-adapter/    - thin OBS glue (C, adapted from obsproject/obs-plugintemplate)
  src/plugin-main.c       obs_module_load/unload + a stub source registration
  src/plugin-support.{h,c.in}
  data/locale/en-US.ini

.gitea/workflows/build.yml   - 3-platform CI matrix (see below)
```

Everything in `core/` is real, working, unit-tested code -- it just doesn't
do anything useful yet (a version string, a config struct with non-empty
validation). Everything in `obs-adapter/` is real OBS module code -- it
registers an actual `obs_source_info` and builds as a real, dynamically
loadable OBS module (see "Verified" below) -- but the source is a stub:
`create`/`destroy` allocate/free a dummy blob, there is no properties UI,
and no frames are ever pushed. That's the boundary this task was scoped to.

## What's real vs. deliberately deferred

Deferred, per the task that produced this scaffold (out of scope for this
pass, in scope for the next one):

- No `livekit-ffi` linkage of any kind.
- No streamer-tools API client (auth, slot-listing, token minting).
- No properties UI (server URL / room slug / read key / camera dropdown).
- No frame output (`obs_source_output_video`/`_audio`).
- No packaging/release step (the design doc's "on a version tag" job).

## Toolchain notes (verified on this machine: Ubuntu 24.04 / Linux)

- **CMake 3.28.3**, **Ninja 1.11.1**, GCC 13.3.0 -- all installed via
  `apt-get install cmake ninja-build`. Top-level `CMakeLists.txt` requires
  CMake >= 3.16 (deliberately lower than the official
  obsproject/obs-plugintemplate's `3.28...3.30` floor -- see below).
- **OBS plugin template used as reference**: obsproject/obs-plugintemplate,
  commit `3e7d7ac3b5342cd7d9b88890b9c70b472d1520fc` (2025-12-09, "Fix typo
  of Visual Studio in README"), fetched fresh from GitHub. `src/plugin-main.c`,
  `src/plugin-support.{h,c.in}`, and the empty `data/locale/en-US.ini` in
  `obs-adapter/` are adapted directly from it.
- **Deliberate deviation from the template's own build system**: the
  official template's `CMakeLists.txt` chains into
  `cmake/common/bootstrap.cmake`, which in turn reads `buildspec.json` and
  *downloads full OBS source archives (pinned to OBS 31.1.1) plus prebuilt
  dependency bundles* for macOS and Windows. That machinery is real,
  actively maintained, and probably the right long-term answer for
  cross-platform reproducible builds -- but it's heavy (multi-hundred-MB
  downloads, a whole `cmake/{macos,windows,common}` support tree, Qt6,
  code-signing hooks) and out of scope to stand up and debug in one pass.
  This scaffold instead uses a much simpler hand-written top-level
  `CMakeLists.txt` that calls `find_package(libobs)` directly.
- **On Linux, this actually works far better than expected**: Ubuntu ships
  a real `libobs-dev` package (`30.0.2+dfsg-3build1` on 24.04, i.e. **not**
  the 31.1.1 the template's buildspec.json pins -- worth reconciling before
  the next phase if API surface matters) with genuine CMake package config
  files (`/usr/lib/x86_64-linux-gnu/cmake/libobs/libobsConfig.cmake`,
  `libobsTargets.cmake`) that export an `OBS::libobs` imported target --
  the exact target name the official template expects. `find_package(libobs
  QUIET)` finds it with zero extra plumbing. This means the OBS adapter in
  this repo links against **real OBS headers and a real `libobs.so`**, not
  a stub -- confirmed by `ldd` showing `libobs.so.0` and `nm -D` showing
  real `obs_module_*` exports (see "Verified" below). Install via
  `apt-get install libobs-dev` (pulls in Qt6 as a dependency chain, ~seconds
  on a fast mirror).
- **macOS/Windows have no equivalent system package** (there's no Homebrew
  formula or winget package that ships `libobsConfig.cmake` the way Ubuntu's
  `libobs-dev` does). For those platforms the choices are: (a) adopt the
  template's full buildspec-driven source/prebuilt-deps download, or (b)
  find/produce a lighter prebuilt SDK bundle. **This is now a concrete,
  scoped decision for the next phase**, not a guess -- the CI workflow in
  this repo currently takes option (c) for this pass only: skip building
  the OBS adapter on macOS/Windows and build+test just the core library,
  via the same `find_package(libobs QUIET)` fallback the top-level
  `CMakeLists.txt` already has for exactly this situation.
- **`ENABLE_QT`/`ENABLE_FRONTEND_API` template options were not carried
  over** -- this scaffold's properties-UI-free stub doesn't need Qt yet;
  the real adapter will need to revisit this once the properties UI
  (server URL / room slug / read key / camera dropdown) is built.

## What actually builds, and how it was verified

```
$ cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
-- libobs found (/usr/lib/x86_64-linux-gnu/cmake/libobs) -- building OBS adapter module
-- Configuring done
-- Generating done

$ cmake --build build
[1/7] Building C object obs-adapter/CMakeFiles/streamer-tools-camera.dir/plugin-support.c.o
[2/7] Building C object obs-adapter/CMakeFiles/streamer-tools-camera.dir/src/plugin-main.c.o
[3/7] Building CXX object core/CMakeFiles/stplugin_core.dir/src/core.cpp.o
[4/7] Linking CXX static library core/libstplugin_core.a
[5/7] Building CXX object core/tests/CMakeFiles/stplugin_core_tests.dir/test_core.cpp.o
[6/7] Linking CXX shared module obs-adapter/streamer-tools-camera.so
[7/7] Linking CXX executable core/tests/stplugin_core_tests

$ ctest --test-dir build --output-on-failure
1/1 Test #1: stplugin_core_tests ..............   Passed    0.00 sec
100% tests passed, 0 tests failed out of 1

$ ldd build/obs-adapter/streamer-tools-camera.so | grep obs
	libobs.so.0 => /lib/x86_64-linux-gnu/libobs.so.0 (...)

$ nm -D build/obs-adapter/streamer-tools-camera.so | grep obs_module
0000000000001430 T obs_module_free_locale
0000000000001450 T obs_module_load
...
0000000000001490 T obs_module_unload
```

This is a genuine, dynamically-linked OBS module -- not the "standalone
shared library without linking OBS" fallback the scaffolding task's scope
explicitly allowed as an acceptable compromise. That fallback path is still
exercised (and needed) on macOS/Windows CI for now; see above.

## CI

`.gitea/workflows/build.yml` runs on every push/PR, matrixed across the
three runners confirmed available to this repo by living under the
`CyberCoveLLC` org (see the design doc's "CI / build pipeline" section):

| Job | `runs-on` | Runner |
|---|---|---|
| `linux` | `ubuntu-latest` | `gitea-runner.internal.cloud-hosting.io` (Global) or `localhost.localdomain` (org-scoped; **note:** now online with `ubuntu-latest`/`ubuntu-24.04`/`ubuntu-22.04` labels -- the design doc recorded it as offline, that's since changed) |
| `macos` | `macos-latest` | `home-mac` (Global) |
| `windows` | `windows-latest` | `winvm-builder` (org-scoped to `CyberCoveLLC`) |

The Linux job installs `libobs-dev` and builds the real OBS adapter module
plus the core library, then runs `ctest`. The macOS/Windows jobs build and
test only the core library for now (see toolchain notes above for why).

No packaging/release step yet -- out of scope for this pass.