Getting Started

Contents

1. Setting Up Your Plugin Project
2. Update Build Dependency Information
3. Platform-Specific Settings
4. Adjust The Build System Settings
5. Configuring And Building Your Plugin

Setting Up Your Plugin Project

After creating a new plugin project and a local clone of it, the template needs to be set up to represent an actual plugin. This is achieved by editing buildspec.json in the repository's root directory:

First, change the metadata of your plugin:

    "name": "plugin-does-something",
    "displayName": "Plugin Does Something For OBS",
    "version": "1.0.0",
    "author": "Plugin Developer",
    "website": "https://plugin-does-something.com",
    "email": "[email protected]",

Note

Many developers in the past have chosen names that mimic the naming scheme used by internal obs-studio modules, e.g. obs-does-something. This practice is discouraged because it makes it more difficult for users to distinguish between modules ("plugins") provided by third parties and those provided by OBS Studio as part of its core functionality, particularly because of the (currently) common practice of copying plugins into the program directory on Windows.

It is thus suggested to use a more memorable unique name or use the "... for OBS" idiom.

Update Build Dependency Information

Next, check the dependencies section in buildspec.json, which is split up into three main parts:

1. obs-studio: Describes the version of OBS Studio to use to build libobs (required to build plugins) and obs-frontend-api (required to build plugins that interact with the OBS Studio user interface)
2. prebuilt: Describes the version of pre-built dependencies for Windows and macOS. These are provided via releases on the obs-deps repository.
3. qt6: Describes the version of a pre-built Qt6 dependency package for Windows and macOS. It is provided via releases on the obs-deps repository as well.

Important

For obs-studio a semantic version name has to be used while for prebuilt and qt6 the build date of the dependencies needs to be used. Their versions need to match with actual releases available on either the obs-studio or obs-deps GitHub repositories.

To ensure that the downloads have not been tampered with, particularly when building and packaging a plugin on CI, SHA-1 checksums for each file have been provided. These checksums have to be updated in tandem with the version:

• For prebuilt and qt6, the corresponding checksums are published on their release page
• For obs-studio, the tar.gz and zip repository archives associated with a release need to be downloaded and their checksums calculated locally

Platform-Specific Settings

Currently only one platform-specific setting needs to be updated in buildspec.json:

    "platformConfig": {
        "macos": {
            "bundleId": "com.example.plugintemplate-for-obs"
        }
    }

macOS requires every binary to have a unique bundle ID, which should follow reverse URL notation. Following the example metadata used above, a possible valid bundle id might be com.plugin-does-something.plugin.

Adjust The Build System Settings

OBS Studio uses CMake as its build system generator and so does the OBS Plugin Template. Developers are absolutely free to scrap the entire build system and use one of their own choice, thus the CMake setup is provided for convenience only.

If the CMake setup is to be used, the file CMakePresets.json is a main entry point for customisation. Details of the file format of CMake presets and how they interact with the build system are available in their official documentation, but some fields are of special note for plugin development.

Tip

It is possible to leave the CMakePresets.json file as-is and instead add a new file called CMakeUserPresets.json. This file can refer to presets used in the main presets file and thus can inherit from them. This way local overrides can be used during development (e.g. increasing the macOS deployment target, enable additional warnings, etc) without impacting other forks or CI.

A hidden "template" preset is used to set up default build settings which will be inherited by all other "visible" presets:

    {
      "name": "template",
      "hidden": true,
      "cacheVariables": {
        "ENABLE_FRONTEND_API": false,
        "ENABLE_QT": false
      }
    }

By default use of obs-frontend-api as well as Qt is disabled. If a plugin intends to interact with the OBS Studio UI via the frontend API, the first value needs to be set to true. If custom Qt-based UI widgets are provided by the plugin, the second value also needs to be set to true.

    {
      "name": "macos",
      "cacheVariables": {
        "CMAKE_OSX_DEPLOYMENT_TARGET": "11.0",
      }
    }

The deployment target identified by the CMake variable CMAKE_OSX_DEPLOYMENT_TARGET describes the lowest macOS version supported. This value should be kept in sync with the same value used by the buildspec.json file used for OBS Studio. Failing to do so can lead to crashes when OBS Studio requires a more recent macOS version than the plugin.

    {
      "name": "windows-x64",
      "generator": "Visual Studio 17 2022",
      "architecture": "x64,version=10.0.22621",
    }

The version specified by the architecture key identifies the Windows SDK version used for compiling the plugin. This value should be kept in sync with the same value used by the buildspec.json file used for OBS Studio. Just like on macOS, failing to do so can lead to undefined behavior or crashes when OBS Studio requires a more recent SDK version than the plugin.

    {
      "name": "ubuntu-x86_64",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
        "CMAKE_INSTALL_LIBDIR": "lib/CMAKE_SYSTEM_PROCESSOR-linux-gnu"
      }
    }

By default the single-configuration variant of ninja is used as the build system for Ubuntu builds. This means that the build configuration can not be changed after generating the build system like on Windows or macOS, but needs to be chosen before. Thus the default build configuration out of the box is RelWithDebInfo, but can either be changed directly or by providing an alternative value as an override on the command line (see the build configuration Wiki page for details).

Important

It is good practice to use non-optimized builds during development, but only ship optimized variants to users. When using CMake, this corresponds to using the "Debug" or "Release" configurations. The "RelWithDebInfo" configuration is a CMake-specific invention:

It configures the compiler to use a lower level of optimizations while still making it embed debug information in the binary, in some way making it the "worst of both worlds". There is no reason not to generate debug information for "Release" builds as well (in fact it is good practice in Visual Studio and Xcode to do so, as they will generate .pdb or .dsym files respectively), but CMake overrides any attempt to do so out of the box.

In fact, to get default Visual Studio and Xcode behavior back, the debug compiler flags need to be manually added to the compiler command line to "undo" CMake's default behavior.

Thus the "RelWithDebInfo" configuration is only used for legacy compatibility reasons, as OBS Studio itself has not followed good practice on this in the past.

Configuring And Building Your Plugin

Note

As mentioned above, the plugin template uses CMake as its build system generator by default. If another build system is used, please refer to its documentation about configuring and actually building your plugin.

Using CMake to generate a build system and build the plugin always follows the same basic steps:

• The first step is called a "configuration" step - CMake will parse the script files strictly in order and create an internal configuration of the project
• Next comes the "generation" step - CMake will now use the configuration built in the first step and create the actual build system files, which can be a hierarchy of Makefiles (for GNU Makefiles), a build.ninja file (for Ninja), or IDE projects (for Visual Studio or Xcode).

Important

It is at this generation step that some more obscure CMake errors can happen. During the configuration phase, CMake works within the model of a "stringly-typed" scripting language, accepting even wrong input (as long as it passes the parser), but it's at the generation phase where CMake will check if provided information is correct.

As an example: The configuration phase will accept any valid string as the name of a source file for the project, but at generation phase CMake needs to resolve the provided file paths and will fail if an invalid path was provided.

• As a third step, CMake can be used to build the project directly - it is aware of the type of project it generated and knows how to invoke the appropriate build system, including the build systems used by Visual Studio and Xcode.
• The fourth step is the "installation" stage, at which point the generated binaries are fixed up (any references to the build system are removed) and the binaries as well as all associated files are gathered and copied into a common destination for the identified project (e.g. on a POSIX system binaries are copied to /usr/local/bin and libraries copied to /usr/local/lib by default).

The template uses this last step to copy the final plugin into a project-specific directory so a distribution archive can be created. The type of this archive is platform-specific but can also be extended by other means (take a look at associated Wiki pages about this topic).