obs-browser

obs-browser introduces a cross-platform Browser Source, powered by CEF (Chromium Embedded Framework), to OBS Studio. A Browser Source allows the user to integrate web-based overlays into their scenes, with complete access to modern web APIs.

On Windows, this also adds support for Service Integration (linking third party services) and Browser Docks (webpages loaded into the interface itself). macOS support for service integration & browser docks is in the works, and Linux support is planned.

This plugin is included by default on official packages on Windows and macOS. While Linux is supported, the official ppa does not currently include the browser source due to a conflict with GTK.

JS Bindings

obs-browser provides a global object that allows access to some OBS-specific functionality from JavaScript. This can be used to create an overlay that adapts dynamically to changes in OBS.

TypeScript Type Definitions

If you're using TypeScript, type definitions for the obs-browser bindings are available through npm and yarn.

# npm
npm install --save-dev @types/obs-studio

# yarn
yarn add --dev @types/obs-studio

Get Browser Plugin Version

/**
 * @returns {string} OBS Browser plugin version
 */
window.obsstudio.pluginVersion
// => 2.17.0

Register for event callbacks

/**
 * @callback EventListener
 * @param {CustomEvent} event
 */

/**
 * @param {string} type
 * @param {EventListener} listener
 */
window.addEventListener('obsSceneChanged', function(event) {
	var t = document.createTextNode(event.detail.name)
	document.body.appendChild(t)
})

Available events

Descriptions for these events can be found here.

• obsSceneChanged
• obsSourceVisibleChanged
• obsSourceActiveChanged
• obsStreamingStarting
• obsStreamingStarted
• obsStreamingStopping
• obsStreamingStopped
• obsRecordingStarting
• obsRecordingStarted
• obsRecordingPaused
• obsRecordingUnpaused
• obsRecordingStopping
• obsRecordingStopped
• obsReplaybufferStarting
• obsReplaybufferStarted
• obsReplaybufferSaved
• obsReplaybufferStopping
• obsReplaybufferStopped
• obsVirtualcamStarted
• obsVirtualcamStopped
• obsExit
• [Any custom event emitted via obs-websocket vendor requests]

Control OBS

Get webpage control permissions

Permissions required: NONE

/**
 * @typedef {number} Level - The level of permissions. 0 for NONE, 1 for READ_OBS (OBS data), 2 for READ_USER (User data), 3 for BASIC, 4 for ADVANCED and 5 for ALL
 */

/**
 * @callback LevelCallback
 * @param {Level} level
 */

/**
 * @param {LevelCallback} cb - The callback that receives the current control level.
 */
window.obsstudio.getControlLevel(function (level) {
    console.log(level)
})

Get OBS output status

Permissions required: READ_OBS

/**
 * @typedef {Object} Status
 * @property {boolean} recording - not affected by pause state
 * @property {boolean} recordingPaused
 * @property {boolean} streaming
 * @property {boolean} replaybuffer
 * @property {boolean} virtualcam
 */

/**
 * @callback StatusCallback
 * @param {Status} status
 */

/**
 * @param {StatusCallback} cb - The callback that receives the current output status of OBS.
 */
window.obsstudio.getStatus(function (status) {
	console.log(status)
})

Get the current scene

Permissions required: READ_USER

/**
 * @typedef {Object} Scene
 * @property {string} name - name of the scene
 * @property {number} width - width of the scene
 * @property {number} height - height of the scene
 */

/**
 * @callback SceneCallback
 * @param {Scene} scene
 */

/**
 * @param {SceneCallback} cb - The callback that receives the current scene in OBS.
 */
window.obsstudio.getCurrentScene(function(scene) {
    console.log(scene)
})

Get scenes

Permissions required: READ_USER

/**
 * @callback ScenesCallback
 * @param {string[]} scenes
 */

/**
 * @param {ScenesCallback} cb - The callback that receives the scenes.
 */
window.obsstudio.getScenes(function (scenes) {
    console.log(scenes)
})

Get transitions

Permissions required: READ_USER

/**
 * @callback TransitionsCallback
 * @param {string[]} transitions
 */

/**
 * @param {TransitionsCallback} cb - The callback that receives the transitions.
 */
window.obsstudio.getTransitions(function (transitions) {
    console.log(transitions)
})

Get current transition

Permissions required: READ_USER

/**
 * @callback TransitionCallback
 * @param {string} transition
 */

/**
 * @param {TransitionCallback} cb - The callback that receives the transition currently set.
 */
window.obsstudio.getCurrentTransition(function (transition) {
    console.log(transition)
})

Save the Replay Buffer

Permissions required: BASIC

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.saveReplayBuffer()

Start the Replay Buffer

Permissions required: ADVANCED

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.startReplayBuffer()

Stop the Replay Buffer

Permissions required: ADVANCED

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.stopReplayBuffer()

Change scene

Permissions required: ADVANCED

/**
 * @param {string} name - Name of the scene
 */
window.obsstudio.setCurrentScene(name)

Set the current transition

Permissions required: ADVANCED

/**
 * @param {string} name - Name of the transition
 */
window.obsstudio.setCurrentTransition(name)

Start streaming

Permissions required: ALL

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.startStreaming()

Stop streaming

Permissions required: ALL

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.stopStreaming()

Start recording

Permissions required: ALL

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.startRecording()

Stop recording

Permissions required: ALL

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.stopRecording()

Pause recording

Permissions required: ALL

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.pauseRecording()

Unpause recording

Permissions required: ALL

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.unpauseRecording()

Start the Virtual Camera

Permissions required: ALL

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.startVirtualcam()

Stop the Virtual Camera

Permissions required: ALL

/**
 * Does not accept any parameters and does not return anything
 */
window.obsstudio.stopVirtualcam()

Register for visibility callbacks

This method is legacy. Register an event listener instead.

/**
 * onVisibilityChange gets callbacks when the visibility of the browser source changes in OBS
 *
 * @deprecated
 * @see obsSourceVisibleChanged
 * @param {boolean} visibility - True -> visible, False -> hidden
 */
window.obsstudio.onVisibilityChange = function(visibility) {

};

Register for active/inactive callbacks

This method is legacy. Register an event listener instead.

/**
 * onActiveChange gets callbacks when the active/inactive state of the browser source changes in OBS
 *
 * @deprecated
 * @see obsSourceActiveChanged
 * @param {bool} True -> active, False -> inactive
 */
window.obsstudio.onActiveChange = function(active) {

};

obs-websocket Vendor

obs-browser includes integration with obs-websocket's Vendor requests. The vendor name to use is obs-browser, and available requests are:

• emit_event - Takes event_name and ?event_data parameters. Emits a custom event to all browser sources. To subscribe to events, see here
  • See #340 for example usage.

There are no available vendor events at this time.

Building

OBS Browser cannot be built standalone. It is built as part of OBS Studio.

By following the instructions, this will enable Browser Source & Custom Browser Docks on all three platforms. Both BUILD_BROWSER and CEF_ROOT_DIR are required.

On Windows

Follow the build instructions and be sure to download the CEF Wrapper and set CEF_ROOT_DIR in CMake to point to the extracted wrapper.

On MacOS

mkdir build
cmake -D CMAKE_XCODE_ATTRIBUTE_CLANG_CXX_LIBRARY=libc++ -G Xcode ..
open cef.xcodeproj/

Building

Build in Xcode (⌘+B)

TODO: tell user to move stuff, or update FindCEF.cmake

Building OBS and obs-browser

Installing Dependencies

brew install ffmpeg x264 qt5 cmake

Setting Up Project

git clone --recursive https://github.com/jp9000/obs-studio.git
cd ./obs-studio
git clone git@github.com:kc5nra/obs-browser.git ./plugins/obs-browser
echo "add_subdirectory(obs-browser)" >> ./plugins/CMakeLists.txt
mkdir build
cd ./build
cmake -D CMAKE_PREFIX_PATH=/usr/local/opt/qt5/lib/cmake -D CEF_ROOT_DIR=/Users/username/Development/cef_binary_3.2883.1540.gedbfb20_macosx64 -D BUILD_BROWSER=yes -G Xcode ..
open obs-studio.xcodeproj/

Building

Build in Xcode (⌘+B)

Building on Windows

Building CEF

Getting

• Download CEF Windows 64bit from https://cef-builds.spotifycdn.com/index.html
• Use CEF branch 3770
• Extract and cd into the folder

Setting Up the Project

• Run cmake-gui
  • In "where is the source code", enter in the repo directory (example: C:/Users/User/Desktop/cef_binary_3.2743.1445.gdad7c0a_windows64).
  • In "where to build the binaries", enter the repo directory path with the 'build' subdirectory (example: C:/Users/User/Desktop/cef_binary_3.2743.1445.gdad7c0a_windows64/build).
• Press 'Configure' and select the generator that fits to your installed VS Version: Visual Studio 12 2013 Win64, Visual Studio 14 2015 Win64 or Visual Studio 15 2017 Win64
• Press 'Generate' to generate Visual Studio project files in the 'build' subdirectory.
• Open cef.sln from the 'build' subdirectory

Building

• Build at least libcef_dll_wrapper (as Release), the rest is optional and are just clients to test with

Building OBS and obs-browser

Follow the OBS build instructions

https://github.com/jp9000/obs-studio/wiki/Install-Instructions#windows

Setting Up Project

On macOS

Use the macOS Full Build Script. This will automatically download & enable OBS Browser.

On Linux

Follow the build instructions and choose the "If building with browser source" option. This includes steps to download/extract the CEF Wrapper, and set the required CMake variables.