A free, open source, and extensible speech-to-text application that works completely offline.
fix(linux): keep transparent overlay painting on WebKitGTK 2.54 (#2360)
Evgeny Khudobaf3d8b876fc10
diff --git a/README.md b/README.mdindex 94b089b8..69b2ef8f 100644--- a/README.md+++ b/README.md@@ -195,7 +195,7 @@ Without these tools, Handy falls back to enigo which may have limited compatibil- For building from source on Ubuntu/Debian, you may also need `libgtk-layer-shell-dev`.- The recording overlay is disabled by default on Linux (`Overlay Position: None`) because certain compositors treat it as the active window. When the overlay is visible it can steal focus, which prevents Handy from pasting back into the application that triggered transcription. If you enable the overlay anyway, be aware that clipboard-based pasting might fail or end up in the wrong window.-- Handy disables the WebKit DMA-BUF renderer by default on Linux, but preserves explicit `WEBKIT_DISABLE_DMABUF_RENDERER` values. For rendering workarounds, see [Troubleshooting → Linux Startup Crashes or Instability](#linux-startup-crashes-or-instability).+- Handy picks the WebKit renderer on Linux from the linked WebKitGTK version: 2.54 and newer keep the compositor on shared memory (`WEBKIT_DMABUF_RENDERER_FORCE_SHM=1`), older releases disable DMA-BUF rendering (`WEBKIT_DISABLE_DMABUF_RENDERER=1`). Explicit values for either variable are preserved. For rendering workarounds, see [Troubleshooting → Configure the WebKit renderer](#3-configure-the-webkit-renderer).- If Handy fails to start reliably on Linux, see [Troubleshooting → Linux Startup Crashes or Instability](#linux-startup-crashes-or-instability).- **Global keyboard shortcuts (Wayland):** On Wayland, system-level shortcuts must be configured through your desktop environment or window manager. Use the [CLI flags](#cli-parameters) as the command for your custom shortcut.@@ -417,23 +417,27 @@ If installing the library does not help, you can skip `gtk-layer-shell` initialiHANDY_NO_GTK_LAYER_SHELL=1 handy```-**3. Configure WebKit DMA-BUF rendering (`WEBKIT_DISABLE_DMABUF_RENDERER`)**+**3. Configure the WebKit renderer (`WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DMABUF_RENDERER_FORCE_SHM`)**-Handy disables the WebKitGTK DMA-BUF renderer by default on Linux because it can cause blank windows or crashes on some GPU/driver combinations. Explicit environment-variable values are preserved, including in the Nix package. To explicitly keep the renderer disabled:+Handy picks the renderer at startup from the WebKitGTK build it links, because the DMA-BUF renderer crashes on some GPU/driver combinations but the non-composited fallback loses pixels on the 2.54 series:++- **WebKitGTK 2.54 and newer:** the compositor stays enabled and is forced onto shared memory with `WEBKIT_DMABUF_RENDERER_FORCE_SHM=1`. 2.54 composites only the damaged region of every frame, so the previous workaround (`WEBKIT_DISABLE_DMABUF_RENDERER=1`) left transparent windows — such as the recording overlay — showing only their animated parts ([#2166](https://github.com/cjpais/Handy/issues/2166)).+- **Older releases:** DMA-BUF rendering is disabled with `WEBKIT_DISABLE_DMABUF_RENDERER=1`, which can cause blank windows but matches the previous behavior.++Explicit environment-variable values are preserved, including in the Nix package:```bash+# Force the legacy non-composited renderer (2.54: partial frames may reappear)WEBKIT_DISABLE_DMABUF_RENDERER=1 handy-```-Some users on WebKitGTK 2.54 report a flickering or partially drawn recording overlay with the renderer disabled ([#2166](https://github.com/cjpais/Handy/issues/2166)). If affected, try opting out of the default workaround:+# Keep the compositor on shared memory (the 2.54 default below)+WEBKIT_DMABUF_RENDERER_FORCE_SHM=1 handy-```bash+# Let WebKit use DMA-BUF when supported (may reintroduce the GPU/driver crashes)WEBKIT_DISABLE_DMABUF_RENDERER=0 handy```-This allows WebKit to use the renderer when supported, but can reintroduce the GPU/driver-specific crashes described above. Remove the override or use `=1` if that happens.--Fully quit Handy, including its tray instance, before testing either value. Running a second instance with `--toggle-transcription` does not change the running process's environment.+Fully quit Handy, including its tray instance, before testing a value. Running a second instance with `--toggle-transcription` does not change the running process's environment.**Making a workaround permanent**diff --git a/flake.nix b/flake.nixindex 13a7646d..0d5df967 100644--- a/flake.nix+++ b/flake.nix@@ -164,7 +164,10 @@preFixup = ''gappsWrapperArgs+=(- --set-default WEBKIT_DISABLE_DMABUF_RENDERER 1+ # Renderer selection (DMA-BUF off vs. forced SHM compositing) is+ # decided at runtime from the linked WebKitGTK version; setting+ # WEBKIT_DISABLE_DMABUF_RENDERER or WEBKIT_DMABUF_RENDERER_FORCE_SHM+ # here or in the environment overrides it.--set ALSA_PLUGIN_DIR "${combinedAlsaPlugins}"# Self-update can't work against an immutable /nix/store install# (downloadAndInstall would try to overwrite the store path), sodiff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lockindex 3a122610..4ba4f25a 100644--- a/src-tauri/Cargo.lock+++ b/src-tauri/Cargo.lock@@ -2522,6 +2522,7 @@ dependencies = ["tempfile","tokio","transcribe-cpp",+ "webkit2gtk-sys","webview2-com","whatlang","windows 0.61.3",diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.tomlindex cbd0ebf7..105eff14 100644--- a/src-tauri/Cargo.toml+++ b/src-tauri/Cargo.toml@@ -168,6 +168,9 @@ objc2-service-management = "0.3.2"[target.'cfg(target_os = "linux")'.dependencies]gtk-layer-shell = { version = "0.8", features = ["v0_6"] }+# Renderer policy in src/webkit_renderer.rs compares the linked WebKitGTK+# version against the release that introduced damage-based compositing.+webkit2gtk-sys = "2.0"gtk = "0.18"transcribe-cpp = { version = "0.4.0", default-features = false, features = ["dynamic-backends",diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rsindex a18c6844..50a7efd7 100644--- a/src-tauri/src/lib.rs+++ b/src-tauri/src/lib.rs@@ -31,6 +31,7 @@ mod transcription_hook;mod tray;mod tray_i18n;mod utils;+pub mod webkit_renderer;pub use cli::CliArgs;#[cfg(debug_assertions)]diff --git a/src-tauri/src/main.rs b/src-tauri/src/main.rsindex 025a42bd..6c59ea8e 100644--- a/src-tauri/src/main.rs+++ b/src-tauri/src/main.rs@@ -5,15 +5,7 @@ use clap::Parser;use handy_app_lib::CliArgs;fn main() {- #[cfg(target_os = "linux")]- {- // DMABUF renderer causes crashes on various GPU/display server configurations- // See: https://github.com/tauri-apps/tauri/issues/9394- // Preserve explicit overrides so affected users can opt out with =0 (#2166).- if std::env::var_os("WEBKIT_DISABLE_DMABUF_RENDERER").is_none() {- std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");- }- }+ handy_app_lib::webkit_renderer::apply();#[cfg(target_os = "windows")]{diff --git a/src-tauri/src/webkit_renderer.rs b/src-tauri/src/webkit_renderer.rsnew file mode 100644index 00000000..8dc68cfd--- /dev/null+++ b/src-tauri/src/webkit_renderer.rs@@ -0,0 +1,65 @@+//! Linux WebKitGTK renderer selection.+//!+//! WebKitGTK 2.54 composites only the damaged region of every frame. With the+//! accelerated compositor replaced by the plain shared-memory path+//! (`WEBKIT_DISABLE_DMABUF_RENDERER=1`, the long-standing workaround for GPU+//! crashes — tauri-apps/tauri#9394) each partial frame arrives in a freshly+//! allocated buffer, so every pixel outside the damage is transparent. For a+//! frameless card like Handy's recording overlay only the animated bits (dot,+//! waveform) survive, which reads as a half-transparent ghost overlay.+//!+//! Keeping the compositor and moving its swap chain to shared memory+//! (`WEBKIT_DMABUF_RENDERER_FORCE_SHM=1`) still bypasses DMA-BUF imports, but+//! paints full frames again. The switch exists since WebKitGTK 2.44; older+//! releases predate both it and the damage tracking, so they keep the previous+//! DMA-BUF-disabled workaround.+//!+//! Explicit user configuration always wins: setting either variable in the+//! environment (shell, desktop entry, Nix wrapper) skips this policy.++/// Applies the WebKitGTK renderer policy for the running WebKit version.+///+/// Must run before GTK/WebKit is initialized. No-op outside Linux.+pub fn apply() {+ #[cfg(target_os = "linux")]+ apply_linux();+}++#[cfg(target_os = "linux")]+fn apply_linux() {+ // Preserve explicit overrides (#2166): users pick their value, and+ // packagers (e.g. the Nix wrapper) can pin the renderer themselves.+ if std::env::var_os("WEBKIT_DISABLE_DMABUF_RENDERER").is_some()+ || std::env::var_os("WEBKIT_DMABUF_RENDERER_FORCE_SHM").is_some()+ {+ return;+ }++ let (major, minor, _micro) = webkit_version();+ if (major, minor) >= (2, 54) {+ // 2.54 repaints only damage, which loses transparent pixels on the+ // non-composited path; keep the compositor on shared memory instead.+ std::env::set_var("WEBKIT_DMABUF_RENDERER_FORCE_SHM", "1");+ log::debug!("webkit renderer: {major}.{minor} -> WEBKIT_DMABUF_RENDERER_FORCE_SHM=1");+ } else {+ // Before the damage tracking the non-composited path is the+ // crash-safe one, so keep the original workaround.+ std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");+ log::debug!("webkit renderer: {major}.{minor} -> WEBKIT_DISABLE_DMABUF_RENDERER=1");+ }+}++/// Version of the WebKitGTK library linked into the process.+#[cfg(target_os = "linux")]+fn webkit_version() -> (u32, u32, u32) {+ // SAFETY: the accessors only read version constants compiled into the+ // WebKitGTK library that wry already links; they neither initialize GTK+ // nor touch any other state.+ unsafe {+ (+ webkit2gtk_sys::webkit_get_major_version(),+ webkit2gtk_sys::webkit_get_minor_version(),+ webkit2gtk_sys::webkit_get_micro_version(),+ )+ }+}