113 lines
5.1 KiB
Markdown
113 lines
5.1 KiB
Markdown
# 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`
|