Little heads up:
OBS seems to have finally gotten a documentation on the API and plugin development so check it out if you need some info after setting up your development environment.
I assume just about everyone who searched for a screen casting software in the last three years has heard of OBS Studio (or formerly just OBS). At this point it is an industry standard for recording and streaming videos. Since the complete rewrite there’s no reason not to use it: it’s free, open-source and cross platform.
A while ago I tried to write a plugin for the original OBS at which I failed tremendously at, for one because of my incompetence but also because it was badly documented and pretty tedious. Recently I got back to that idea of writing a plugin for it but now since it switched to being crossplatform the process changed completely.
Sadly it’s still pretty obscure, which shows in the fact that there’s barely any plugins for OBS Studio. It seems like the setup process is what keeps a lot of people from making a plugin and those who get it to work stop after finding out that there’s no real documentation (Except code comments). After spending about two days on setting OBS Studio up, I got it to work and after some more time spent I finished my plugin.
It adds a new source type to OBS which shows keyboard and mouse input on stream. If you want to check it out you can get it here. But now I’ll talk a little about the setup process.
Working with OBS Studio’s source code
This post is rather long so if you don’t like reading you can watch my video tutorial:
The only real documentation is the guide up on github. But even with those instructions some things are a little unclear. For this guide I’ll assume you want to set up a development environment on windows.
So first of the requirements:
- Visual Studio (2013 or 2015)
- Git (Recommended)
Visual Studio 2017 was just released but I had no luck when trying to use it so I used VS 2013 Community. The following parts will show you how to set up all requirements, except Visual Studio, just google for the installer of the desired version and install it.
Now you should set up a dedicated folder for your development with obs (here refered to as “obs-dev/”) and download the dependencies first (Dependencies for Visual Studio 2013/2015). Unzip them and put them in a sub folder (here refered to as “obs-deps”).
It’s not all that obvious as to how to get Qt5, since the guide only mentions folder names like
D:\Qt\5.8\msvc2013_64. So first head to the Qt page and download the installer. Then skip the login part and select only these options when installing (These are the required ones, since everyting else just takes up disk space):
Now obviously if you have Visual Studio 2013 you dont need msvc2015 and the other way around. Also if you only want to develop for 64 bit you don’t need 32 bit and vice versa. You can uncheck everything else, except the Qt creator since that ones required.
Note: You can only install Qt to a path that does not contain spaces, in my case
Cmake is the software OBS uses to configure the environment for developing and it will take care of all the complicated stuff. So just install it, or download a portable version from the offical cmake page.
This is only used to grab the source code and if you want to keep track of your changes. Get it here.
Putting it all together
Now let’s put all these new toys to use: First grab the source code from github via git. Open git bash (by default right click in your obs-dev folder and choose “open git bash here”) then enter this command
git clone --recursive https://github.com/jp9000/obs-studio.git
now you’ll have a sub folder called obs-studio, nice! Though this is the very latest and bleeding edge stuff. That’s cool if you’re planning to just build OBS or contribute to it’s development, but if you want to develop a plugin it’s better to use the latest stable release, so let’s turn back time to the latest stable release. Type:
git tag -l
This will list all past releases of obs studio. At the bottom there should be the latest version (eg. 20.0.1), now let’s load that version by running
git checkout 20.0.1
or if you plan on using git to track your changes
git checkout 20.0.1 -b plugin-dev
The second command will create a new branch with the name “plugin-dev”, this assures that all your future changes will be tracked on a separate branch without touching the original obs code (You obviously can’t acutally change the original code without having the right permissions, but it still helps to keep your local repository tidy).
That’s all we need from git, we now have stable releas of OBS we can base our plugin on.
This step is only needed if you want to develop a plugin for OBS, if you just want to compile it or want to direcetly commit to the obs repository (in pull-requests), you can directly go to “Using Cmake”
Cmake by default only creates project files for OBS and it’s plugins. But our plugin isn’t included since it doesn’t exist yet. Let’s fix that by telling cmake to create an empty project for us. Head into “obs-dev/obs-studio/plugins” and create a new sub folder for your plugin (in this case “test-plugin”). Now inside that folder you need a file called “CmakeLists.txt” and a *.c or *.cpp file with the same name as your plugin. You can keep it empty, but we need something to fill your project for now. The last thing you need is a “data” folder with another folder called “locale”. Inside that you put your language files to translate your plugin (by default only “en_US.ini”.
So this is how your folder structure should look like by now:
Now we can leave all files empty except the CMakeLists.txt. This needs to contain information for Cmake so it can create the project. You can take a look at other plugins or copy what I have:
Just replace all instances of “test-plugin” with your plugin name. The last thing we need to do is go back to the “plugins” folder and edit the CMakeLists.txt file which is inside that folder. At the bottom of that file you’ll see a bunch of “add_subdirectory(…)” lines. Just add another line with your plugin and save it.
And that is all you need to do to tell CMake about your plugin, now we’ll let CMake take care of the rest.
Open up the Cmake-gui and then set “Where is the source code:” to “obs-dev/obs-studio” and “Where to build the binaries” to a separate folder where you want to have all Visual Studio projects (it won’t actually put the binaries there), for me the folder is “obs-dev/obs-studio/vs”. Now click configure and select the Visual Studio version you use. You can choose between “Visual Studio <2013/2015>” and “Visual Studio <2013/2015> Win64”. Using 64 bit means your project will build 64 bit binaries and the same for 32 bit.
After it’s done it’ll spit out some errors since it can’t smell where you put the dependencies. You’ll have to set two variables QTDIR and DepsPath. Both of these can be suffixed with “32” or “64” to tell Cmake what bit the dependencies are. So you either just set QTDIR, or if you want both 64 and 32 bit you’ll set QTDIR32 and QTDIR64. For me this is how I set them:
- QTDIR32: C:/Qt/5.8/msvc2013
- QTDIR64: C:/Qt/5.8/mscv2013_64
- DepsPath32: ../obs-dev/obs-deps/win32
- DepsPath64: ../obs-dev/obs-deps/win64
Note: Cmake uses forward slashes for paths since all Operating systems do that except Windoze.
In this screenshot I only used the 64 bit dependencies, which means I can directly use “DepsPath” and “QTDIR”. If you want 32bit and/or 64bit you’ll need to click “Add entry” and add “DepsPath32” / “DepsPath64” and “QTDIR32” / “QTDIR64”, and set their values accordingly.
Keep in mind that the dependencies are different for VS 2013 and 2015! Now click configure again and after it finishes it’ll let you change some other settings which are unimportant for us so just click configure a third time and there should be no red items in the Cmake list left. After all that you can click Generate, which will create the Visual Studio Solution. When that is done you can click Open Project or directly open the solution.
This is how Cmake should look like after the second configuring process (After you entered “DepsPath” & “QTDIR”).
And that’s it. Give VisualSudio some time since OBS is a huge project and it takes some time to index all the files. You should now be able to click the green play button and the latest version of OBS should run. If you configured CMake to create a project for your plugin you should also see a project with your plugin name in the project explorer.
So this was all I had to go through to develop a small pugin that probably no one will use. If you compare this essay to the guide up on github you’ll see that it’s missing a couple of things. For experienced developers this process might be self explanatory but for a newbie like me it was quite the nerve wrecking adventure. Maybe this write up will prevent at least one persone from going throught that same process.