# 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

```sh
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:

```sh
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:

```sh
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`