OBS-WebKitGTK/README.md

OBS WebKit Browser Source (No CEF)

A native browser input source for OBS Studio on Alpine Linux. Pages are rendered by the system WebKitGTK 4.1 in a separate process; the project does not use Chromium/CEF or Xvfb. The renderer uses the X11/XWayland display inherited from OBS and keeps its WebView in a fully transparent, non-interactive native window. WebKitGTK needs this native surface to import GPU DMA-BUF buffers. Frames are sent directly to OBS as BGRA without FFmpeg or desktop capture.

Features:

• HTTP/HTTPS and data: URLs, plus local HTML files;
• transparent backgrounds with an alpha channel;
• custom CSS;
• 25–500% page zoom saved in source or web panel settings;
• optional per-source audio capture as a separate OBS Audio Mixer channel;
• dimensions from 2 to 8192 px and frame rates from 1 to 60 FPS;
• hardware-accelerated WebKit compositing through DRM/DMA-BUF (Mesa radeonsi on AMD);
• direct XComposite/XShm capture of composited GPU frames with alpha;
• XDamage-based skipping of backing pixmap reads while page content is unchanged;
• shared-memory frame transport without sending multi-megabyte frames through a pipe;
• mouse, scrolling, focus, and basic keyboard input through the OBS Interact window;
• page reload and optional renderer shutdown while a source is hidden;
• custom web panels in the OBS Docks menu, with URLs stored in the scene collection, restored on startup, and full interactive input;
• one shared persistent WebKit profile for scene sources and web panels, including cookies, HTTP cache, localStorage, IndexedDB, service workers, and credentials; same-origin pages communicate through standard storage events and BroadcastChannel, just like browser tabs.

Audio capture is disabled by default. Enable Capture browser audio in the source settings to add its audio as a separate OBS Audio Mixer channel. Capture requires a running PulseAudio-compatible server (including PipeWire Pulse) and the GStreamer pulsesink; the dependency installation script installs the required gst-plugins-good package.

All WebViews in one OBS session share a renderer process and a single WebKitWebContext. Small proxy processes preserve the independent lifetime of each source or dock and isolate them from OBS. The profile is stored in the standard user data and cache directories under obs-webkit-browser/profile and survives OBS restarts.

The renderer inherits the X11/XWayland display from OBS. Its native window has zero opacity and an empty input shape, so it does not appear on the desktop. No additional display server is started. WebKit is forced to use its hardware compositor and selects an available DRM render node, which requires access to /dev/dri/renderD*.

For expensive full-screen filter: blur() effects, use the actual widget size instead of rendering at 4K/1080p and scaling the source down in the scene. Custom will-change declarations and compositor hints are preserved, but the renderer does not inject them itself; WebKit assigns elements to GPU layers.

This is a working backend, not a replacement for every advanced feature in the standard obs-browser plugin. DevTools, the cookies API, and DRM are not currently available.

Building on Alpine

chmod +x scripts/install-deps-alpine.sh
./scripts/install-deps-alpine.sh
/usr/bin/cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
/usr/bin/cmake --build build
ctest --test-dir build --output-on-failure
doas /usr/bin/cmake --install build --prefix /usr

After installation, restart OBS and add a WebKit Browser source. To add a panel, open Docks → Custom Web Panels..., enter its name and URL, and click Apply. Panels can be shown or hidden through the regular Docks menu; right-click a page to reload it. If OBS uses a non-standard prefix, set OBS_PLUGIN_DIR and OBS_PLUGIN_DATA_DIR during configuration.

Release Archive

After installing the dependencies, use the dedicated Makefile targets:

make build
make test
doas make install
make archive

make build creates a Release build, make test runs the tests, doas make install installs the plugin into /usr, and make archive builds and tests the project before creating a package without installing it. The archive obs-webkit-browser-<version>-linux-<arch>.tar.gz and its SHA-256 file are written to dist/. The archive contains no absolute paths, only the user plugin layout obs-webkit-browser/{bin/64bit,data}. Install it directly into the OBS user plugin directory:

mkdir -p ~/.config/obs-studio/plugins
tar -xzf dist/obs-webkit-browser-<version>-linux-<arch>.tar.gz \
  -C ~/.config/obs-studio/plugins

Why WebKitGTK Instead of WPE?

WPE would be the best architectural fit, but the wpewebkit package is not available in current Alpine edge/3.24; only libwpe and the backend remain. WebKitGTK 4.1 is available in the current Alpine repository, uses the same WebKit, and does not depend on CEF. The renderer is isolated from OBS, so a Web process crash should not bring down the studio.

Donations

• TRC20: TYxUB8Vey9xh7jS9cPU2R34eT97pAN851v
• TON: UQDBYC5TfbQLsgf50xtBaq9jtyhMl4klwJIeWh6HY_fWim42