From 1556334c0e9e06dd63e8c02382b3ecac4924e59b Mon Sep 17 00:00:00 2001 From: WarmUpTill Date: Sun, 14 Aug 2022 05:53:45 +0200 Subject: [PATCH] Update README.md and BUILDING.md * Add "Contributing" section * Update build instructions --- BUILDING.md | 161 +++++++++++++++------------------------------------- README.md | 25 ++++---- 2 files changed, 61 insertions(+), 125 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 407330e5..10b5a9f5 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -4,11 +4,9 @@ You have the option to ... - either add the plugin to the OBS source tree directly and build the plugin while building OBS itself. (**in tree**) - or you can move the sources of this plugin outside of the OBS source tree and build it separately from OBS. (**out of tree**) -As both methods require you to have a working [OBS Studio development environment](https://obsproject.com/wiki/install-instructions), [Qt](https://download.qt.io/official_releases/qt/5.15/5.15.2/) and [CMake](https://cmake.org/download/) it is recommended to build the plugin in tree as it is easier to set up and will enable straightforward debugging. +As both methods require you to have a working [OBS Studio development environment](https://obsproject.com/wiki/Building-OBS-Studio) and [CMake](https://cmake.org/download/) it is recommended to build the plugin in tree as it is easier to set up and will enable straightforward debugging. -Note that your Qt install must include the QtConcurrent module. - -## Compiling in tree (recommended) +## Compiling in tree (recommended for development) Add the "SceneSwitcher" source directory to your obs-studio source directory under obs-studio/UI/frontend-plugins/: ``` cd obs-studio/UI/frontend-plugins/ @@ -20,7 +18,7 @@ Then modify the obs-studio/UI/frontend-plugins/CMakeLists.txt file and add an en add_subdirectory(SceneSwitcher) ``` -Now follow the [build instructions for obs-studio](https://obsproject.com/wiki/install-instructions) for your particular platform. +Now follow the [build instructions for obs-studio](https://obsproject.com/wiki/Building-OBS-Studio) for your particular platform. Note that on Linux systems it might be necessary to additionally install the following packages to fulfill the dependencies to `XTest`, `XScreensaver` and `OpenCV` - exact command may differ: ``` @@ -32,121 +30,54 @@ sudo apt-get install \ ## Compiling out of tree -### Prerequisites -You'll need [Qt](https://download.qt.io/official_releases/qt/5.15/5.15.2/), [CMake](https://cmake.org/download/) and a working [OBS Studio development environment](https://obsproject.com/wiki/install-instructions) installed on your computer. -Once you've set this up, do the following: + +First you will need to clone the plugin sources by running the following command: ``` git clone --recursive https://github.com/WarmUpTill/SceneSwitcher.git cd SceneSwitcher +``` + +You'll need [CMake](https://cmake.org/download/) and a working [OBS Studio development environment](https://obsproject.com/wiki/Building-OBS-Studio) installed on your computer. +The easiest way to set this up is to call the corresponding CI scripts, as they will automatically download all required dependencies and start build of the plugin: + +| Platform | Command | +| ----------- | ----------- | +| Windows | `.\.github\scripts\Build-Windows.ps1` | +| Linux | `.\.github\scripts\build-linux.sh` | +| MacOS | `.\.github\scripts\build-macos.zsh` | + +Alternatively you can download the OBS dependencies from https://github.com/obsproject/obs-deps/releases and manually configure and start the build. + +Start by creating a build directory: +``` mkdir build && cd build ``` - -### Windows -In cmake-gui, you'll have to set these CMake variables : -- **BUILD_OUT_OF_TREE** (bool) : true - -- **LIBOBS_LIB** (filepath) : location of the obs.lib file -- **LIBOBS_INCLUDE_DIR** (path) : location of the libobs subfolder in the source -code of OBS Studio, located at [source_directory]/libobs/. - -- **LIBOBS_FRONTEND_API_LIB** (filepath) : location of the obs-frontend-api.lib file -(usually in the same place as LIBOBS_LIB) -- **LIBOBS_FRONTEND_INCLUDE_DIR** (path) : location of the obs-frontend-api -subfolder in the source code of OBS Studio, located at [source_directory]/UI/obs-frontend-api. - -- **CURL_LIBRARY** (filepath) : location of the libcurl.lib file -(part of the dependencies2019/win64/bin folder used to build OBS) -- **CURL_INCLUDE_DIR** (path) : location of the curl -subfolder in OBS dependencies folder: ".../dependencies2019/win64/include/" - - -Assuming that you set up Qt via QT installer: -- **Qt5Core_DIR** (path) : C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5Core -- **Qt5Gui_DIR** (path): C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5Gui -- **Qt5Widgets_DIR** (path) : C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5Widgets - -Just keep hitting configure until all the vars are filled out. Then hit generate. - -### Linux -Install dependencies `XTest`, `XScreensaver` and `OpenCV` - exact command may differ: +Next configure the build. ``` -sudo apt-get install \ - libxtst-dev \ - libxss-dev \ - libopencv-dev +cmake -DCMAKE_PREFIX_PATH= -Dlibobs_DIR= -Dobs-frontend-api_DIR= .. +``` +It might be necessary to provide additional variables depending on your build setup. +Finally, start the plugin build using your provided generator. (E.g. Ninja on Linux or a Visual Studio solution on Windows) + +# Contributing + +Contributions to the plugin are always welcome and if you need any assistance do not hesitate to reach out. + +In general changes in the `src\legacy` folder should be avoided. + +If you would like to expand upon the macro system by adding a new condition or action type have a loot at the examples in `src\macro-core`. +The key functions to add conditions or are the Register() functions. + +``` +MacroActionFactory::Register( + MacroActionExample::id, // Unique string identifying this action type + { + MacroActionExample::Create, // Function called to create the object performing the action + MacroActionExampleEdit::Create, // Function called to create the widget configure the action + "AdvSceneSwitcher.action.example" // User facing name of the action type + } + ); ``` -Most versions of Linux you can use cmake-gui or the command line. - -**For the command line:** -``` -# [...] are placeholders -cmake -DBUILD_OUT_OF_TREE=1 \ --DLIBOBS_INCLUDE_DIR=[...]/obs-studio/libobs/ \ --DLIBOBS_LIB=[...]/libobs.so \ --DLIBOBS_FRONTEND_INCLUDE_DIR=[...]/obs-studio/UI/obs-frontend-api/ \ --DLIBOBS_FRONTEND_API_LIB=[...]/libobs-frontend-api.so \ --DCMAKE_INSTALL_PREFIX=/usr .. -make -j4 -sudo make install -``` - -For cmake-gui you'll have to set the following variables: -- **BUILD_OUT_OF_TREE** (bool) : true -- **LIBOBS_INCLUDE_DIR** (path) : location of the libobs subfolder in the source -code of OBS Studio, located at [source_directory]/libobs/. -- **LIBOBS_LIB** (filepath) : location of the libobs.so file (usually CMake finds -this, but if not it'll usually be in /usr/lib/libobs.so) -- **LIBOBS_FRONTEND_API_LIB** (filepath) : location of the libobs-frontend-api.so -file (usually in the same place as LIBOBS_LIB) -- **LIBOBS_FRONTEND_INCLUDE_DIR** (path) : location of the obs-frontend-api -subfolder in the source code of OBS Studio, located at -[source_directory]/UI/obs-frontend-api. - -Assuming that you installed Qt via your system package manager, it should be -found automatically. If not, then usually you'll find it in something like: -- **Qt5Core_DIR** (path) : /usr/lib64/cmake/Qt5Core -- **Qt5Gui_DIR** (path): /usr/lib64/cmake/Qt5Gui -- **Qt5Widgets_DIR** (path) : /usr/lib64/cmake/Qt5Widgets - -Just keep hitting configure until all the vars are filled out. Then hit generate. - -Then open a terminal in the build folder and type: -``` -make -j4 -sudo make install -``` -NOTE: The Linux version of this plugin is dependent on libXScrnSaver, libcurl and libXtst. - -### OS X -In cmake-gui, you'll have to set these CMake variables : -- **BUILD_OUT_OF_TREE** (bool) : true -- **LIBOBS_INCLUDE_DIR** (path) : location of the libobs subfolder in the source -code of OBS Studio, located at [source_directory]/libobs/. -- **LIBOBS_LIB** (filepath) : location of the libobs.0.dylib file (usually -in /Applications/OBS.app/Contents/Resources/bin/libobs.0.dylib) -- **LIBOBS_FRONTEND_API_LIB** (filepath) : location of the libobs-frontend-api.0.dylib -file (usually in usually in /Applications/OBS.app/Contents/Resources/bin/libobs-frontend-api.0.dylib) -- **LIBOBS_FRONTEND_INCLUDE_DIR** (path) : location of the obs-frontend-api subfolder -in the source code of OBS Studio, located at [source_directory]/UI/obs-frontend-api. - -Assuming that you installed Qt via the regular Qt App way: -- **Qt5Core_DIR** (path) : Usually /Applications/Qt/5.10.1/clang_64/lib/cmake/Qt5Core -- **Qt5Widgets_DIR** (path) : Usually /Applications/Qt/5.10.1/clang_64/lib/cmake/Qt5Widgets -- **Qt5MacExtras_DIR** (path) : Usually /Applications/Qt/5.10.1/clang_64/lib/cmake/Qt5MacExtras - - -Just keep hitting configure until all the vars are filled out. Then hit generate. - -Open xcode (or a terminal, depending on the build type you chose), build and copy -the advanced-scene-switcher.so file to 'Library/Application Support/obs-studio/plugins/advanced-scene-switcher/bin/' -And the 'data' folder to 'Library/Application Support/obs-studio/plugins/advanced-scene-switcher/'. - -Note that you might have to adjust the library search paths using the install_name_tool if you want the plugin to run on machines other than your build machine: -``` -install_name_tool -change @rpath/libobs-frontend-api.dylib @executable_path/../Frameworks/libobs-frontend-api.dylib UI/frontend-plugins/SceneSwitcher/advanced-scene-switcher.so -install_name_tool -change @rpath/libobs.0.dylib @executable_path/../Frameworks/libobs.0.dylib UI/frontend-plugins/SceneSwitcher/advanced-scene-switcher.so -install_name_tool -change /usr/local/opt/qt5/lib/QtWidgets.framework/Versions/5/QtWidgets @executable_path/../Frameworks/QtWidgets.framework/Versions/5/QtWidgets UI/frontend-plugins/SceneSwitcher/advanced-scene-switcher.so -install_name_tool -change /usr/local/opt/qt5/lib/QtGui.framework/Versions/5/QtGui @executable_path/../Frameworks/QtGui.framework/Versions/5/QtGui UI/frontend-plugins/SceneSwitcher/advanced-scene-switcher.so -install_name_tool -change /usr/local/opt/qt5/lib/QtCore.framework/Versions/5/QtCore @executable_path/../Frameworks/QtCore.framework/Versions/5/QtCore UI/frontend-plugins/SceneSwitcher/advanced-scene-switcher.so -``` +If your intention is to add macro functionality which depends on external libraries, which is likely not to exist on all user setups, try to follow the examples under `src\macro-external`. +These are basically plugins themselves that get attempted to be loaded on startup of the advanced scene switcher. \ No newline at end of file diff --git a/README.md b/README.md index c3d5df96..8f7ec108 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # SceneSwitcher -An automated scene switcher for OBS Studio. +An automation plugin for OBS Studio. More information can be found on https://obsproject.com/forum/resources/automatic-scene-switching.395/. @@ -9,23 +9,28 @@ Binaries for Windows, MacOS, and Linux are available in the [Releases](https://g ## Installing the plugin -For the Windows and MacOS platforms, it is recommended to run the provided installers. +For the **Windows** and **MacOS** platforms, it is recommended to run the provided installers. -For Linux the Snap package manager offers an OBS Studio installation which is bundled with the plugin: +For **Linux** the **Snap** package manager offers an OBS Studio installation which is bundled with the plugin: ``` sudo snap install obs-studio ``` -The plugin is also available via the Flatpak package manager for users who installed OBS via Flatpak: +The plugin is also available via the **Flatpak** package manager for users who installed OBS via Flatpak: ``` flatpak install com.obsproject.Studio.Plugin.SceneSwitcher ``` -If that is not an option you will have to ... -1. Copy the library to the plugins folder of you obs installation. -2. Copy the contents of the data directory to its respective folders of your obs installation. +Also note that the Linux version of this plugin has the following dependencies to `XTest`, `XScreensaver` and optionally `OpenCV`. +If `apt` is supported on your system they can be installed using: +``` +sudo apt-get install \ + libxtst-dev \ + libxss-dev \ + libopencv-dev +``` -Unfortunately the exact location of these folders may vary from system to system. +## Contributing -## Compiling the plugin +- If you wish to contribute code to the project, have a look at this [section](BUILDING.md) describing how to compile the plugin. +- If you wish to contribute translations, feel free to submit pull requests for the corresponding files under `data/locale`. -See the [build instructions](BUILDING.md).