The plugin template is meant to be used as a starting point for OBS Studio plugin development. It includes:
The plugin project is set up using the included buildspec.json
file. The following fields should be customized for an actual plugin:
name
: The plugin nameversion
: The plugin versionauthor
: Actual name or nickname of the plugin's authorwebsite
: URL of a website associated with the pluginemail
: Contact email address associated with the pluginuuids
macosPackage
: Unique (!) identifier for the macOS plugin packagemacosInstaller
: Unique (!) identifier for the macOS plugin installerwindowsApp
: Unique (!) identifier for the Windows plugin installerThese values are read and processed automatically by the CMake build scripts, so no further adjustments in other files are needed.
Platform-specific settings are set up in the platformConfig
section of the buildspec file:
bundleId
: macOS bundle identifier for the plugin. Should be unique and follow reverse domain name notation.Just like OBS Studio itself, plugins need to be built using dependencies available either via the obs-deps
repository (Windows and macOS) or via a distribution's package system (Linux).
By default the plugin template specifies the most current official OBS Studio version in the buildspec.json
file, which makes most sense for plugins at the start of development. As far as updating the targeted OBS Studio version is concerned, a few things need to be considered:
libobs
might not be compatibleOn Linux, the version used for development might be decided by the specific version available via a distribution's package management system, so OBS Studio compatibility for plugins might be determined by those versions instead.
Windows and macOS dependency downloads are configured in the buildspec.json
file:
dependencies
:
obs-studio
: Version of OBS Studio to build plugin with (needed for libobs
and obs-frontend-api
)prebuilt
: Prebuilt OBS Studio dependenciesqt6
: Prebuilt version of Qt6 as used by OBS Studiotools
: Contains additional build tools used by CIThe values should be kept in sync with OBS Studio releases and the buildspec.json
file in use by the main project to ensure that the plugin is developed and built in sync with its target environment.
To update a dependency, change the version
and associated hashes
entries to match the new version. The used hash algorithm is sha256
.
Linux dependencies need to be resolved using the package management tools appropriate for the local distribution. As an example, building on Ubuntu requires the following packages to be installed:
cmake
ninja-build
pkg-config
build-essential
libobs-dev
qt6-base-dev
libqt6svg6-dev
qt6-base-private-dev
To create a build configuration, cmake
needs to be installed on the system. The plugin template supports CMake presets using the CMakePresets.json
file and ships with default presets:
macos
6
11.0
macos-ci
macos
windows-x64
6
10.0.18363.657
windows-ci-x64
windows-x64
linux-x86_64
6
RelWithDebInfo
build configurationlinux-ci-x86_64
linux-x86_64
linux-aarch64
6
RelWithDebInfo
build configurationlinux-ci-aarch64
linux-aarch64
Presets can be either specified on the command line (cmake --preset <PRESET>
) or via the associated select field in the CMake Windows GUI. Only presets appropriate for the current build host are available for selection.
Additional build system options are available to developers:
ENABLE_CCACHE
: Enables support for compilation speed-ups via ccache (enabled by default on macOS and Linux)ENABLE_FRONTEND_API
: Adds OBS Frontend API support for interactions with OBS Studio frontend functionality (disabled by default)ENABLE_QT
: Adds Qt6 support for custom user interface elements (disabled by default)CODESIGN_IDENTITY
: Name of the Apple Developer certificate that should be used for code signingCODESIGN_TEAM
: Apple Developer team ID that should be used for code signingDefault GitHub Actions workflows are available for the following repository actions:
push
: Run for commits or tags pushed to master
or main
branches.pr-pull
: Run when a Pull Request has been pushed or synchronized.dispatch
: Run when triggered by the workflow dispatch in GitHub's user interface.build-project
: Builds the actual project and is triggered by other workflows.check-format
: Checks CMake and plugin source code formatting and is triggered by other workflows.The workflows make use of GitHub repository actions (contained in .github/actions
) and build scripts (contained in .github/scripts
) which are not needed for local development, but might need to be adjusted if additional/different steps are required to build the plugin.
Successful builds on GitHub Actions will produce build artifacts that can be downloaded for testing. These artifacts are commonly simple archives and will not contain package installers or installation programs.
To create a release, an appropriately named tag needs to be pushed to the main
/master
branch using semantic versioning (e.g., 12.3.4
, 23.4.5-beta2
). A draft release will be created on the associated repository with generated installer packages or installation programs attached as release artifacts.
Plugins released for macOS should be codesigned and notarized with a valid Apple Developer ID for best user experience. To set this up, the private and personal key of a paid Apple Developer ID need to be downloaded from the Apple Developer portal:
The developer certificate will usually carry a name similar in form to
Developer ID Application: <FIRSTNAME> <LASTNAME> (<LETTERS_AND_NUMBERS>)
This entire string should be specified as CODESIGN_IDENTITY
, the LETTERS_AND_NUMBERS
part as CODESIGN_TEAM
to CMake to set up codesigning properly.
To use code signing on GitHub Actions, the certificate and associated information need to be set up as repository secrets in the GitHub repository's settings.
base64 <NAME_OF_YOUR_P12_FILE>
MACOS_SIGNING_APPLICATION_IDENTITY
: Name of the "Developer ID Application" signing certificateMACOS_SIGNING_INSTALLER_IDENTITY
: Name of "Developer ID Installer" signing certificateMACOS_SIGNING_CERT
: The base64 encoded .p12
fileMACOS_SIGNING_CERT_PASSWORD
: Password used to generate the .p12 certificateMACOS_NOTARIZATION_USERNAME
: Your Apple Developer account's Apple IDMACOS_NOTARIZATION_PASSWORD
: Your Apple Developer account's generated app password