commit 105f1041ab869030bc6a153d589f08f7da40cfca Author: Claude Sonnet 5 Date: Sun Sep 6 20:46:08 2026 -0700 Scaffold core/OBS-adapter split, prove CMake toolchain, add 3-platform CI First pass on the streamer-tools OBS camera plugin: a minimal but real CMake project matching the design doc's core-library/OBS-adapter split (docs/superpowers/specs/2026-09-06-obs-camera-plugin-design.md in the streamer-tools repo). No LiveKit FFI integration yet -- this proves the toolchain works. - core/: dependency-free C++17 library (no OBS dependency), unit tested via CTest with no external test framework. - obs-adapter/: adapted from obsproject/obs-plugintemplate (commit 3e7d7ac, 2025-12-09). Registers a real, stubbed OBS source type; builds as a genuine dynamically-linked OBS module against Ubuntu's system libobs-dev (confirmed via ldd/nm, not a fake stand-in). - Simpler hand-written top-level CMakeLists.txt in place of the template's full buildspec-driven bootstrap (which downloads full OBS source + prebuilt deps) -- find_package(libobs) alone is enough on Linux; falls back to core-library-only when libobs isn't found (expected on macOS/Windows CI for now). - .gitea/workflows/build.yml: 3-platform matrix (ubuntu-latest, macos-latest, windows-latest) matching the runners confirmed available to this repo under the CyberCoveLLC org. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01RL8abRmgFXkVASHkkqiJbE diff --git a/.gitea/workflows/build.yml b/.gitea/workflows/build.yml new file mode 100644 index 0000000..a572cd2 --- /dev/null +++ b/.gitea/workflows/build.yml @@ -0,0 +1,72 @@ +name: Build + +# Scaffolding CI: proves the CMake toolchain configures and builds on all +# three platforms the design doc names. It does not yet link livekit-ffi +# or produce a real OBS-installable package -- see README.md. + +on: + push: + pull_request: + +jobs: + linux: + name: Linux (ubuntu-latest) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install build dependencies + run: | + sudo apt-get update -qq + sudo apt-get install -y -qq cmake ninja-build libobs-dev + + - name: Configure + run: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release + + - name: Build + run: cmake --build build + + - name: Test (core library) + run: ctest --test-dir build --output-on-failure + + macos: + name: macOS (macos-latest) + runs-on: macos-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install build dependencies + run: brew install cmake ninja + + - name: Configure + # libobs is not expected to be found here yet (no Homebrew + # formula / SDK download wired up in this pass) -- the top-level + # CMakeLists.txt falls back to building only the core library in + # that case. See README.md. + run: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release + + - name: Build + run: cmake --build build + + - name: Test (core library) + run: ctest --test-dir build --output-on-failure + + windows: + name: Windows (windows-latest) + runs-on: windows-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Configure + # Same story as macOS: no OBS SDK available yet on this runner, + # so this proves the core library + MSVC toolchain only. + run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release + + - name: Build + run: cmake --build build --config Release + + - name: Test (core library) + run: ctest --test-dir build -C Release --output-on-failure diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a4fb4fb --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +build/ +.cache/ diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..2be358a --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,36 @@ +cmake_minimum_required(VERSION 3.16) + +project(obs-streamer-tools-plugin + VERSION 0.0.1 + DESCRIPTION "OBS Studio source plugin for streamer-tools camera feeds (scaffold, no LiveKit integration yet)" + LANGUAGES C CXX +) + +set(CMAKE_C_STANDARD 11) +set(CMAKE_C_STANDARD_REQUIRED ON) +set(CMAKE_CXX_STANDARD 17) +set(CMAKE_CXX_STANDARD_REQUIRED ON) + +enable_testing() + +# --- Scaffolding note ------------------------------------------------------ +# This deliberately does NOT use the full obsproject/obs-plugintemplate +# build system (its cmake/common/bootstrap.cmake + buildspec.json, which +# download complete OBS source archives and prebuilt dependency bundles +# for macOS/Windows). That machinery is real and may be worth adopting +# wholesale in a later phase; for this scaffolding pass the goal is a much +# simpler CMakeLists.txt that proves out find_package(libobs) plus the +# core/adapter split on the platform we can actually verify locally +# (Linux, via the system libobs-dev package). See README.md for the full +# writeup of what was verified vs. what remains. +# ---------------------------------------------------------------------------- + +add_subdirectory(core) + +find_package(libobs QUIET) +if(libobs_FOUND) + message(STATUS "libobs found (${libobs_DIR}) -- building OBS adapter module") + add_subdirectory(obs-adapter) +else() + message(WARNING "libobs NOT found -- skipping OBS adapter module; core library still builds/tests") +endif() diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1b8a5cd --- /dev/null +++ b/LICENSE @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + {description} + Copyright (C) {year} {fullname} + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + {signature of Ty Coon}, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..3bbf6f8 --- /dev/null +++ b/README.md @@ -0,0 +1,159 @@ +# 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. diff --git a/core/CMakeLists.txt b/core/CMakeLists.txt new file mode 100644 index 0000000..618c517 --- /dev/null +++ b/core/CMakeLists.txt @@ -0,0 +1,20 @@ +# streamer-tools OBS Camera Plugin - core library +# +# No OBS dependency by design (see docs/superpowers/specs/ +# 2026-09-06-obs-camera-plugin-design.md in the streamer-tools repo) -- +# this must build and test headlessly on every platform. + +add_library(stplugin_core STATIC + src/core.cpp +) + +target_include_directories(stplugin_core + PUBLIC + ${CMAKE_CURRENT_SOURCE_DIR}/include +) + +set_target_properties(stplugin_core PROPERTIES + POSITION_INDEPENDENT_CODE ON +) + +add_subdirectory(tests) diff --git a/core/include/stplugin/core.h b/core/include/stplugin/core.h new file mode 100644 index 0000000..28de919 --- /dev/null +++ b/core/include/stplugin/core.h @@ -0,0 +1,57 @@ +/* +streamer-tools OBS Camera Plugin - core library +Copyright (C) 2026 CyberCoveLLC + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see +*/ + +#pragma once + +#include + +// C++ API for the core library. Per the design doc +// (docs/superpowers/specs/2026-09-06-obs-camera-plugin-design.md in the +// streamer-tools repo), this library will eventually own: streamer-tools +// API auth, LiveKit FFI session management (connect, subscribe, decode, +// reconnect), and frame callbacks -- all with zero OBS dependency, so it +// can be built and tested headlessly. +// +// THIS IS SCAFFOLDING. Nothing below talks to a real server or to +// livekit-ffi yet. It exists to prove the core-library/OBS-adapter split +// builds, links, and is unit-testable, ahead of a later phase that +// implements the real logic. + +namespace stplugin { + +// Returns the core library's version string. Placeholder for a real +// version scheme once the library does something. +const char *core_version(); + +// Minimal connection configuration the future core library will use to +// authenticate against the streamer-tools API +// (see apps/server/src/rooms/join.routes.ts and +// apps/server/src/livekit/tokens.ts in the streamer-tools repo for the +// existing read-key-authed token pattern this will follow) and mint a +// scoped LiveKit subscriber token. Validation here is intentionally +// trivial -- it exists to prove the core library is unit-testable +// headlessly, not to implement the real API client. +struct ConnectionConfig { + std::string server_url; + std::string room_slug; + std::string read_key; + + bool is_valid() const; +}; + +} // namespace stplugin diff --git a/core/include/stplugin/core_c.h b/core/include/stplugin/core_c.h new file mode 100644 index 0000000..eb6f384 --- /dev/null +++ b/core/include/stplugin/core_c.h @@ -0,0 +1,38 @@ +/* +streamer-tools OBS Camera Plugin - core library +Copyright (C) 2026 CyberCoveLLC + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see +*/ + +#pragma once + +// Minimal C ABI surface of the core library, for the OBS adapter (plain +// C, per the obs-plugintemplate convention) to call into the core +// library (C++) without needing a C++ compiler in that translation unit. +// +// This mirrors the boundary the real integration will cross in the +// other direction: livekit-ffi is a Rust library exposing a C ABI that +// the C++ core library will link against. Proving a small, deliberate +// C ABI seam works cleanly here is part of what this scaffold is for. + +#ifdef __cplusplus +extern "C" { +#endif + +const char *stplugin_core_version(void); + +#ifdef __cplusplus +} +#endif diff --git a/core/src/core.cpp b/core/src/core.cpp new file mode 100644 index 0000000..f9e2fc7 --- /dev/null +++ b/core/src/core.cpp @@ -0,0 +1,36 @@ +/* +streamer-tools OBS Camera Plugin - core library +Copyright (C) 2026 CyberCoveLLC + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see +*/ + +#include "stplugin/core.h" +#include "stplugin/core_c.h" + +namespace stplugin { + +const char *core_version() { + return "0.0.1-scaffold"; +} + +bool ConnectionConfig::is_valid() const { + return !server_url.empty() && !room_slug.empty() && !read_key.empty(); +} + +} // namespace stplugin + +extern "C" const char *stplugin_core_version(void) { + return stplugin::core_version(); +} diff --git a/core/tests/CMakeLists.txt b/core/tests/CMakeLists.txt new file mode 100644 index 0000000..c517532 --- /dev/null +++ b/core/tests/CMakeLists.txt @@ -0,0 +1,7 @@ +add_executable(stplugin_core_tests + test_core.cpp +) + +target_link_libraries(stplugin_core_tests PRIVATE stplugin_core) + +add_test(NAME stplugin_core_tests COMMAND stplugin_core_tests) diff --git a/core/tests/test_core.cpp b/core/tests/test_core.cpp new file mode 100644 index 0000000..521c600 --- /dev/null +++ b/core/tests/test_core.cpp @@ -0,0 +1,59 @@ +/* +streamer-tools OBS Camera Plugin - core library tests +Copyright (C) 2026 CyberCoveLLC + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see +*/ + +// Deliberately dependency-free (no gtest/catch2 etc.) so this test target +// has no network fetch or package-manager step in CI -- proving the +// "core library builds and tests headlessly, no OBS required" claim +// without adding another moving part to this scaffolding pass. + +#include +#include +#include + +#include "stplugin/core.h" +#include "stplugin/core_c.h" + +int main() { + // core_version() should return a non-empty string, via both the + // C++ API and the C ABI wrapper the OBS adapter will actually call. + const char *cpp_version = stplugin::core_version(); + assert(cpp_version != nullptr); + assert(std::strlen(cpp_version) > 0); + + const char *c_version = stplugin_core_version(); + assert(c_version != nullptr); + assert(std::strcmp(cpp_version, c_version) == 0); + + // ConnectionConfig::is_valid() -- trivial non-empty checks, but + // exercised through all four combinations to prove the core library + // is genuinely testable in isolation. + stplugin::ConnectionConfig valid{"https://streamers.example.com", "main-room", "readkey123"}; + assert(valid.is_valid()); + + stplugin::ConnectionConfig missing_url{"", "main-room", "readkey123"}; + assert(!missing_url.is_valid()); + + stplugin::ConnectionConfig missing_slug{"https://streamers.example.com", "", "readkey123"}; + assert(!missing_slug.is_valid()); + + stplugin::ConnectionConfig missing_key{"https://streamers.example.com", "main-room", ""}; + assert(!missing_key.is_valid()); + + std::printf("core: all tests passed\n"); + return 0; +} diff --git a/obs-adapter/CMakeLists.txt b/obs-adapter/CMakeLists.txt new file mode 100644 index 0000000..d5be005 --- /dev/null +++ b/obs-adapter/CMakeLists.txt @@ -0,0 +1,37 @@ +# streamer-tools OBS Camera Plugin - OBS adapter +# +# Thin glue only, per the design doc: source registration, (eventually) +# properties UI, and pushing frames into OBS. All real logic lives in +# ../core. Only added to the build when find_package(libobs) succeeds +# (see top-level CMakeLists.txt) -- see README.md for why. + +set(STPLUGIN_PROJECT_NAME "streamer-tools-camera") +set(STPLUGIN_PROJECT_VERSION "${PROJECT_VERSION}") + +configure_file( + src/plugin-support.c.in + ${CMAKE_CURRENT_BINARY_DIR}/plugin-support.c + @ONLY +) + +add_library(${STPLUGIN_PROJECT_NAME} MODULE + src/plugin-main.c + ${CMAKE_CURRENT_BINARY_DIR}/plugin-support.c +) + +target_include_directories(${STPLUGIN_PROJECT_NAME} + PRIVATE + ${CMAKE_CURRENT_SOURCE_DIR}/src + ${CMAKE_CURRENT_BINARY_DIR} +) + +target_link_libraries(${STPLUGIN_PROJECT_NAME} + PRIVATE + OBS::libobs + stplugin_core +) + +set_target_properties(${STPLUGIN_PROJECT_NAME} PROPERTIES + PREFIX "" + OUTPUT_NAME ${STPLUGIN_PROJECT_NAME} +) diff --git a/obs-adapter/data/locale/en-US.ini b/obs-adapter/data/locale/en-US.ini new file mode 100644 index 0000000..7d2a041 --- /dev/null +++ b/obs-adapter/data/locale/en-US.ini @@ -0,0 +1,2 @@ +# streamer-tools OBS Camera Plugin - en-US locale +# No user-facing strings yet -- this is scaffolding (see plugin-main.c). diff --git a/obs-adapter/src/plugin-main.c b/obs-adapter/src/plugin-main.c new file mode 100644 index 0000000..cc86c13 --- /dev/null +++ b/obs-adapter/src/plugin-main.c @@ -0,0 +1,74 @@ +/* +streamer-tools OBS Camera Plugin +Copyright (C) 2026 CyberCoveLLC + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see +*/ + +/* SCAFFOLDING. This registers a source type so the OBS-adapter/core- + * library split and OBS's module-loading toolchain can be proven end to + * end, but it does not do anything real yet: no LiveKit FFI session, no + * frames pushed via obs_source_output_video/audio, no properties UI. + * See docs/superpowers/specs/2026-09-06-obs-camera-plugin-design.md in + * the streamer-tools repo for what this becomes. */ + +#include +#include +#include +#include + +OBS_DECLARE_MODULE() +OBS_MODULE_USE_DEFAULT_LOCALE(PLUGIN_NAME, "en-US") + +static const char *stcam_source_get_name(void *unused) +{ + UNUSED_PARAMETER(unused); + return "streamer-tools Camera (scaffold - not yet functional)"; +} + +static void *stcam_source_create(obs_data_t *settings, obs_source_t *source) +{ + UNUSED_PARAMETER(settings); + UNUSED_PARAMETER(source); + /* No LiveKit session, no state to speak of yet -- just proving the + * source registers and OBS can instantiate/destroy it cleanly. */ + return bzalloc(1); +} + +static void stcam_source_destroy(void *data) +{ + bfree(data); +} + +static struct obs_source_info streamer_tools_camera_source = { + .id = "streamer_tools_camera_source", + .type = OBS_SOURCE_TYPE_INPUT, + .output_flags = OBS_SOURCE_ASYNC_VIDEO, + .get_name = stcam_source_get_name, + .create = stcam_source_create, + .destroy = stcam_source_destroy, +}; + +bool obs_module_load(void) +{ + obs_log(LOG_INFO, "streamer-tools camera plugin scaffold loaded (core library version %s)", + stplugin_core_version()); + obs_register_source(&streamer_tools_camera_source); + return true; +} + +void obs_module_unload(void) +{ + obs_log(LOG_INFO, "streamer-tools camera plugin scaffold unloaded"); +} diff --git a/obs-adapter/src/plugin-support.c.in b/obs-adapter/src/plugin-support.c.in new file mode 100644 index 0000000..1e06535 --- /dev/null +++ b/obs-adapter/src/plugin-support.c.in @@ -0,0 +1,43 @@ +/* +streamer-tools OBS Camera Plugin +Copyright (C) 2026 CyberCoveLLC + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see +*/ + +/* Adapted from obsproject/obs-plugintemplate (commit 3e7d7ac, + * 2025-12-09), the standard starting point for third-party OBS + * plugins. */ + +#include "plugin-support.h" + +const char *PLUGIN_NAME = "@STPLUGIN_PROJECT_NAME@"; +const char *PLUGIN_VERSION = "@STPLUGIN_PROJECT_VERSION@"; + +void obs_log(int log_level, const char *format, ...) +{ + size_t length = 4 + strlen(PLUGIN_NAME) + strlen(format); + + char *template = malloc(length + 1); + + snprintf(template, length, "[%s] %s", PLUGIN_NAME, format); + + va_list(args); + + va_start(args, format); + blogva(log_level, template, args); + va_end(args); + + free(template); +} diff --git a/obs-adapter/src/plugin-support.h b/obs-adapter/src/plugin-support.h new file mode 100644 index 0000000..4403ec1 --- /dev/null +++ b/obs-adapter/src/plugin-support.h @@ -0,0 +1,42 @@ +/* +streamer-tools OBS Camera Plugin +Copyright (C) 2026 CyberCoveLLC + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see +*/ + +/* Adapted from obsproject/obs-plugintemplate (commit 3e7d7ac, + * 2025-12-09), the standard starting point for third-party OBS + * plugins. */ + +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include +#include +#include + +extern const char *PLUGIN_NAME; +extern const char *PLUGIN_VERSION; + +void obs_log(int log_level, const char *format, ...); +extern void blogva(int log_level, const char *format, va_list args); + +#ifdef __cplusplus +} +#endif