Distribute Your Plugin

Contents

1. Plugin Distribution Basics
2. Packaging
3. Good Distribution Practices

Plugin Distribution Basics

Plugin developers are free to distribute their plugins in any way that does not violate OBS Studio's GPL license and its "OPEN BROADCASTER SOFTWARE" and "OBS" trademarks.

Caution

As any plugin requires at the very least the libobs library to provide its core functionality, it is the OBS Project's opinion that any plugin falls under what the GPL considers a "combined work" and thus your plugin becomes a "derivative work". This requires any plugin developer to make the source code of any distributed plugin available to people who have received a binary copy of the plugin in some form as well.

There are no specific ways in which a plugin needs to be distributed. Possible choices are:

• Publishing the source code via a public repository only
• Creating compressed archives of pre-built binaries (made available as .zip files for Windows users and .tar.gz or .tar.xz files for Linux and macOS users)
• Creating platform-specific installation packages (installer programs on Windows, package installers on macOS, system packages on Linux)
• Uploading generated archives and installers to a separate web host and offering direct download links
• Having GitHub Actions automatically generate compressed archives and installers of pre-built binaries and creating GitHub releases of the plugin
• Creating and maintaining a plugin resource at the OBS Plugin Repository

These are not mutually exclusive and developers can choose the variants that are most suitable to them.

Packaging

The simplest way to package a plugin is to combine all files into a compressed archive and distribute it, which requires users to know where to put these files on their local machine. While this is not secret knowledge (it might require a quick internet search to find that information), it still represents additional work that one might not want users to repeat each time they install or update a plugin.

Installers and installer packages can be generated that take care of putting a plugin's files in the correct location without much or any user input. Each platform has a different system to achieve this (and some platforms themselves might provide several different options for this as well).

As explained in OBS Plugin File Structure, plugin files need to be put into correct places in a specific directory structure, or else OBS Studio will not be able to load a plugin or load the plugin's language and support files.

Windows

As there is no single "official" way to install applications on Windows, many different solutions have been commonly used to create installers (including, but not limited to InstallShield, NSIS, InnoSetup, Wise, and others) with a few even offered by Microsoft itself.

Tip

As plugins require at the very least Windows 10 to work, Microsoft's most recent offering MSIX might be a viable "native" alternative to third party installers.

While the OBS Project has chosen a specific installer for its own distribution, there is no need to (or benefit to) using the same for your plugin - you are free to chose whichever solution works best for you.

For convenience, a Guide to Add InnoSetup Packages is available, which can be used as an example implementation that can be adapted for different installers.

macOS

While macOS applications are commonly just copied from a disk image into the "Applications" directory, anything that needs to go to specific locations in the file system commonly prefers to use installer packages identified by their parcel symbol and the .pkg file extension.

Installer packages are archives that contain metadata that describes the package as well as where files are supposed to be copied to and also support JavaScript code in their XML-based metadata files. Because installer packages are a feature of macOS itself, we suggest plugin developers make use of it as well.

Note

The plugin template generates macOS installer package metadata files and corresponding installer packages by default. The GitHub Actions workflow uses these files to automatically attach them to a generated release.

Ubuntu/Linux

Software distribution on Linux follows a different model than Windows or macOS: Users commonly install a Linux distribution which contains a specific version of the Linux kernel and a bundled compatible set of libraries and applications at a specific version as "packages". Not all of these packages are automatically installed and instead made available through a package manager, which is capable to look for and install packages matching a user's description.

Important

Each Linux distribution might also choose to use a different package manager (the formats, tools, and standards used to store, distribute, and install packages). While Debian and Debian-derived distributions like Ubuntu use apt, RedHat and its derivatives use rpm, whereas Arch and derivatives use pacman, OpenSUSE uses zypper, and Gentoo uses portage.

Due to this, there is no single way to distribute your OBS Studio plugin: Each distribution will require a different way to package your plugin and adding your plugin to the official distributions might come with additional challenges and requirements.

In addition to the package managers provided by the Linux distributions there are also independent solutions like Flatpak or Snap which aim to decouple applications (and their plugins) from the system distribution and which use their own distribution channels.

Thus it's up to the developer to choose which distributions to provide packages for and how to distribute them. Similar to how OBS Studio only provides pre-compiled .deb packages for Ubuntu on CI, the plugin template will only generate plain Ubuntu .deb packages as well.

Caution

The plugin template uses CMake's cpack tool to generate DEB packages. Unfortunately this generator seems only capable of generating .deb packages that can be used on Ubuntu and are not fully compatible with Debian (even though that's where the .deb suffix has its origins).

Good Distribution Practices

OBS Studio is a project with active development, which not only means that features are added or refined constantly, but bugs are fixed, ambiguities are resolved and behavior can change. While the OBS Project puts in a lot of good-faith effort not to break plugins (particularly within the same major version of the API), some changes might be inevitable.

As an example, OBS Studio might need to update some of its core dependencies (e.g. Qt), which by themselves have introduced breaking changes. Any plugin that makes direct use of such a dependency will be affected by this update as well and will need to move along with the main project.

Caution

Failure to do so has the potential to crash OBS Studio at any point (with Qt in particular, possible crashes might only occur on specific UI interactions) and thus will lead to user disappointment. Worse, the crash will usually be attributed to OBS Studio itself at first, which will require its maintainers to spend time and effort to figure out that it was indeed the plugin that is the cause of a crash.

In general it is good practice to:

• Follow OBS Studio development and proactively recognize changes that will negatively impact the plugin
• The plugin should be tested and updated once a new beta update for OBS Studio has been released
  • If possible, a beta-version update of the plugin should be distributed as well to benefit from beta users of OBS Studio testing the update ahead of a full release
• Only use libobs and obs-frontend-api. Do not use private or internal APIs.
• Do not use any of the OBS Studio dependencies (e.g. FFmpeg, Python, libx264) yourself.

Important

The only exception to this rule is Qt - while it carries the same risk as using FFmpeg et. al., the OBS Project is aware of this risk and will try to mitigate it and proactively identify possible breaking changes for plugin developers. It is the only dependency this effort is made for.