waymirror 0.1.0__tar.gz

waymirror-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/

waymirror-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Initial release.
+- Mirror a region of a Wayland screen into an ordinary GTK4 window via the
+  xdg-desktop-portal ScreenCast portal + PipeWire + GStreamer.
+- `REGION` accepts `WxH+X+Y`, `left`, `right`, or nothing (whole monitor).
+- Borderless, exact-size window locked to the region's aspect ratio (no
+  letterbox bars even when the compositor caps the height to the work area).
+- `q`/`Esc` to quit; `--no-cursor`; persistent portal restore token.
+- Optional desktop integration via the `waymirror-setup install` command
+  (launcher entry + icon in the user's XDG directories).

waymirror-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Senko Rasic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

waymirror-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: waymirror
+Version: 0.1.0
+Summary: Mirror a region of a Wayland screen into a normal window.
+Project-URL: Homepage, https://github.com/senko/waymirror
+Project-URL: Repository, https://github.com/senko/waymirror
+Project-URL: Issues, https://github.com/senko/waymirror/issues
+Author-email: Senko Rasic <senko@senko.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gnome,gstreamer,gtk4,mirror,pipewire,screen,screen-sharing,screencast,wayland,xdg-desktop-portal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: GTK
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Desktop Environment :: Gnome
+Classifier: Topic :: Multimedia :: Video :: Capture
+Requires-Python: >=3.11
+Provides-Extra: bindings
+Requires-Dist: pygobject>=3.50; extra == 'bindings'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# waymirror
+
+Mirror a **region of a Wayland screen into an ordinary window** — so any meeting
+app (Google Meet, Teams, Jitsi, Slack, …) can share *that window* and show your
+selected region.
+
+This is useful when your screencast app only lets you share either a whole screen
+or a single window, but you want to share *part* of your screen - for example, if
+you have a ultra-widescreen monitor.
+
+It's the answer to "this app only lets me share a whole screen or a window, but I
+want to share *part* of my screen." Point waymirror at a region; share the
+waymirror window.
+
+## How it works
+
+
+Waymirror:
+
+1. opens an **xdg-desktop-portal** `ScreenCast` session and gets a **PipeWire**
+   stream of a monitor (the compositor shows its own picker for *which* monitor;
+   you can't hand it a region, so we capture the whole monitor),
+2. **crops** the stream to your region with GStreamer's `videocrop`
+   (HiDPI-aware — the crop is computed from the negotiated buffer size vs. the
+   monitor's logical size),
+3. renders the result into a borderless **GTK4** window via `gtk4paintablesink`.
+
+Pipeline: `pipewiresrc → videoconvert → videocrop → gtk4paintablesink`.
+
+Because it relies on the desktop portal, waymirror works on **GNOME** and other
+portal-supporting compositors (KDE, wlroots-based). It also runs under X11
+sessions that provide the portal, but it's built for Wayland.
+
+## Requirements
+
+The heavy lifting is done by **system** components (PyGObject, GStreamer plugins,
+the GObject-Introspection typelibs, GTK4). These are **not** installable from PyPI
+in a working way, so install them from your distribution first.
+
+**Debian / Ubuntu** (verified on Debian 13 "trixie"):
+
+```bash
+sudo apt install \
+  python3-gi gir1.2-gtk-4.0 gir1.2-gstreamer-1.0 gir1.2-gst-plugins-base-1.0 \
+  gstreamer1.0-pipewire gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
+  gstreamer1.0-gl gstreamer1.0-gtk4
+```
+
+**Fedora** (package names may vary by release):
+
+```bash
+sudo dnf install \
+  python3-gobject gtk4 \
+  gstreamer1-plugins-base gstreamer1-plugins-good \
+  pipewire-gstreamer gstreamer1-plugins-rs
+```
+
+**Arch**:
+
+```bash
+sudo pacman -S \
+  python-gobject gtk4 \
+  gst-plugins-base gst-plugins-good gst-plugin-pipewire gst-plugins-rs
+```
+
+The pieces you need, whatever the package names: **PyGObject**, **GTK 4** +
+typelib, **GStreamer** core + typelibs, and the elements `pipewiresrc`,
+`videoconvert`, `videocrop`, and `gtk4paintablesink` (the last comes from the
+GStreamer **Rust** plugins / `gstreamer1.0-gtk4`). waymirror checks these at
+startup and tells you exactly what's missing.
+
+## Install
+
+Because the bindings live on the system, install waymirror into an environment
+that can see them. The easiest is pipx with system site packages:
+
+```bash
+pipx install --system-site-packages waymirror
+```
+
+With `uv` from source / for development:
+
+```bash
+git clone https://github.com/senko/waymirror
+cd waymirror
+uv venv --python /usr/bin/python3 --system-site-packages
+uv pip install -e .
+```
+
+> The `--system-site-packages` flag (and `--python /usr/bin/python3` for uv) is
+> what lets the venv use the distro's `gi`/GStreamer. A plain isolated venv won't
+> find them.
+
+Prefer pip to build the bindings instead? Install the build headers for your
+distro and use the `bindings` extra: `pip install "waymirror[bindings]"` (you
+still need the native GStreamer plugins).
+
+## Usage
+
+```bash
+waymirror 800x600+100+100     # explicit region (+X+Y optional, defaults to +0+0)
+waymirror left                # exact left half of the selected monitor
+waymirror right               # exact right half
+waymirror                     # whole selected monitor
+waymirror right --no-cursor   # hide the mouse pointer in the mirror
+waymirror --help
+```
+
+With `left`/`right`, waymirror reads the monitor size from the portal and splits
+it in two — you don't need to know the resolution.
+
+The first run shows the portal picker (choose the monitor your region is on); the
+choice is remembered via a restore token in `~/.config/waymirror/restore-token`,
+so later runs don't prompt.
+
+### The window
+
+- **No title bar**, opens at exactly the region size.
+- Locked to the region's **aspect ratio**; if it's resized (eg. to accomodate
+  the GNOME title bar), it keeps the aspect rate automatically.
+- Quit with **`q`**, **`Esc`**, or `Ctrl-C`. Run several at once for several
+  regions.
+- Move the window with `Super+drag`.
+- `-v` / `WAYMIRROR_DEBUG=1` for verbose logging.
+
+## Desktop integration (optional)
+
+waymirror is a CLI tool, but you can register a launcher entry + icon so GNOME
+shows a proper name and icon for the window — in the dock/overview *and* in the
+meeting app's window picker. It's a separate, opt-in command (installs into your
+user XDG directories, no root needed):
+
+```bash
+waymirror-setup install      # ~/.local/share/applications + .../icons
+waymirror-setup uninstall
+```
+
+## Development
+
+```bash
+uv venv --python /usr/bin/python3 --system-site-packages
+uv pip install -e ".[dev]"
+python -m unittest discover -s tests    # or: pytest
+python -m waymirror left                # run without installing
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+

waymirror-0.1.0/README.md

@@ -0,0 +1,150 @@
+# waymirror
+
+Mirror a **region of a Wayland screen into an ordinary window** — so any meeting
+app (Google Meet, Teams, Jitsi, Slack, …) can share *that window* and show your
+selected region.
+
+This is useful when your screencast app only lets you share either a whole screen
+or a single window, but you want to share *part* of your screen - for example, if
+you have a ultra-widescreen monitor.
+
+It's the answer to "this app only lets me share a whole screen or a window, but I
+want to share *part* of my screen." Point waymirror at a region; share the
+waymirror window.
+
+## How it works
+
+
+Waymirror:
+
+1. opens an **xdg-desktop-portal** `ScreenCast` session and gets a **PipeWire**
+   stream of a monitor (the compositor shows its own picker for *which* monitor;
+   you can't hand it a region, so we capture the whole monitor),
+2. **crops** the stream to your region with GStreamer's `videocrop`
+   (HiDPI-aware — the crop is computed from the negotiated buffer size vs. the
+   monitor's logical size),
+3. renders the result into a borderless **GTK4** window via `gtk4paintablesink`.
+
+Pipeline: `pipewiresrc → videoconvert → videocrop → gtk4paintablesink`.
+
+Because it relies on the desktop portal, waymirror works on **GNOME** and other
+portal-supporting compositors (KDE, wlroots-based). It also runs under X11
+sessions that provide the portal, but it's built for Wayland.
+
+## Requirements
+
+The heavy lifting is done by **system** components (PyGObject, GStreamer plugins,
+the GObject-Introspection typelibs, GTK4). These are **not** installable from PyPI
+in a working way, so install them from your distribution first.
+
+**Debian / Ubuntu** (verified on Debian 13 "trixie"):
+
+```bash
+sudo apt install \
+  python3-gi gir1.2-gtk-4.0 gir1.2-gstreamer-1.0 gir1.2-gst-plugins-base-1.0 \
+  gstreamer1.0-pipewire gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
+  gstreamer1.0-gl gstreamer1.0-gtk4
+```
+
+**Fedora** (package names may vary by release):
+
+```bash
+sudo dnf install \
+  python3-gobject gtk4 \
+  gstreamer1-plugins-base gstreamer1-plugins-good \
+  pipewire-gstreamer gstreamer1-plugins-rs
+```
+
+**Arch**:
+
+```bash
+sudo pacman -S \
+  python-gobject gtk4 \
+  gst-plugins-base gst-plugins-good gst-plugin-pipewire gst-plugins-rs
+```
+
+The pieces you need, whatever the package names: **PyGObject**, **GTK 4** +
+typelib, **GStreamer** core + typelibs, and the elements `pipewiresrc`,
+`videoconvert`, `videocrop`, and `gtk4paintablesink` (the last comes from the
+GStreamer **Rust** plugins / `gstreamer1.0-gtk4`). waymirror checks these at
+startup and tells you exactly what's missing.
+
+## Install
+
+Because the bindings live on the system, install waymirror into an environment
+that can see them. The easiest is pipx with system site packages:
+
+```bash
+pipx install --system-site-packages waymirror
+```
+
+With `uv` from source / for development:
+
+```bash
+git clone https://github.com/senko/waymirror
+cd waymirror
+uv venv --python /usr/bin/python3 --system-site-packages
+uv pip install -e .
+```
+
+> The `--system-site-packages` flag (and `--python /usr/bin/python3` for uv) is
+> what lets the venv use the distro's `gi`/GStreamer. A plain isolated venv won't
+> find them.
+
+Prefer pip to build the bindings instead? Install the build headers for your
+distro and use the `bindings` extra: `pip install "waymirror[bindings]"` (you
+still need the native GStreamer plugins).
+
+## Usage
+
+```bash
+waymirror 800x600+100+100     # explicit region (+X+Y optional, defaults to +0+0)
+waymirror left                # exact left half of the selected monitor
+waymirror right               # exact right half
+waymirror                     # whole selected monitor
+waymirror right --no-cursor   # hide the mouse pointer in the mirror
+waymirror --help
+```
+
+With `left`/`right`, waymirror reads the monitor size from the portal and splits
+it in two — you don't need to know the resolution.
+
+The first run shows the portal picker (choose the monitor your region is on); the
+choice is remembered via a restore token in `~/.config/waymirror/restore-token`,
+so later runs don't prompt.
+
+### The window
+
+- **No title bar**, opens at exactly the region size.
+- Locked to the region's **aspect ratio**; if it's resized (eg. to accomodate
+  the GNOME title bar), it keeps the aspect rate automatically.
+- Quit with **`q`**, **`Esc`**, or `Ctrl-C`. Run several at once for several
+  regions.
+- Move the window with `Super+drag`.
+- `-v` / `WAYMIRROR_DEBUG=1` for verbose logging.
+
+## Desktop integration (optional)
+
+waymirror is a CLI tool, but you can register a launcher entry + icon so GNOME
+shows a proper name and icon for the window — in the dock/overview *and* in the
+meeting app's window picker. It's a separate, opt-in command (installs into your
+user XDG directories, no root needed):
+
+```bash
+waymirror-setup install      # ~/.local/share/applications + .../icons
+waymirror-setup uninstall
+```
+
+## Development
+
+```bash
+uv venv --python /usr/bin/python3 --system-site-packages
+uv pip install -e ".[dev]"
+python -m unittest discover -s tests    # or: pytest
+python -m waymirror left                # run without installing
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+

waymirror-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "waymirror"
+dynamic = ["version"]
+description = "Mirror a region of a Wayland screen into a normal window."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Senko Rasic", email = "senko@senko.net" }]
+keywords = [
+    "wayland", "screen", "mirror", "screencast", "screen-sharing",
+    "pipewire", "gstreamer", "gtk4", "xdg-desktop-portal", "gnome",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: X11 Applications :: GTK",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Desktop Environment :: Gnome",
+    "Topic :: Multimedia :: Video :: Capture",
+]
+# Runtime depends on SYSTEM packages (PyGObject + GStreamer plugins + GI
+# typelibs + GTK4) that cannot be reliably installed from PyPI. See README.
+dependencies = []
+
+[project.optional-dependencies]
+# Convenience for users who prefer pip to build the Python bindings instead of
+# the distro's python3-gi. You STILL need the native GStreamer plugins +
+# typelibs from your distro.
+bindings = ["PyGObject>=3.50"]
+dev = ["pytest"]
+
+[project.scripts]
+waymirror = "waymirror.cli:main"
+# optional desktop integration (launcher + icon); run after install:
+#   waymirror-setup install
+waymirror-setup = "waymirror.desktop:main"
+
+[project.urls]
+Homepage = "https://github.com/senko/waymirror"
+Repository = "https://github.com/senko/waymirror"
+Issues = "https://github.com/senko/waymirror/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/waymirror/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/waymirror"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/waymirror", "tests", "README.md", "LICENSE", "CHANGELOG.md"]

waymirror-0.1.0/src/waymirror/__init__.py

@@ -0,0 +1,10 @@
+"""waymirror - mirror a region of a Wayland screen into a normal window.
+
+On Wayland (and GNOME in particular) you cannot read another window's pixels or
+create a virtual monitor the way X11 tools do. waymirror instead asks the
+xdg-desktop-portal ScreenCast portal for a PipeWire stream of a monitor, crops
+it to the region you ask for, and shows it in an ordinary GTK4 window -- which a
+meeting app can then share as a *window* (sharp), not as a blurred camera feed.
+"""
+
+__version__ = "0.1.0"

waymirror-0.1.0/src/waymirror/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

waymirror-0.1.0/src/waymirror/app.py

@@ -0,0 +1,236 @@
+"""GTK4 application: portal stream -> crop -> window."""
+
+import logging
+import os
+
+import gi
+
+gi.require_version("Gst", "1.0")
+gi.require_version("Gtk", "4.0")
+gi.require_version("Gdk", "4.0")
+from gi.repository import Gdk, GLib, Gio, Gst, Gtk  # noqa: E402
+
+from .geometry import compute_crop, fit_within_bounds, resolve_half
+from .portal import (
+    CURSOR_MODE_EMBEDDED,
+    CURSOR_MODE_HIDDEN,
+    PortalScreenCast,
+)
+
+log = logging.getLogger(__name__)
+
+APP_ID = "hr.dobarkod.waymirror"
+
+
+def _restore_token_path():
+    return os.path.join(GLib.get_user_config_dir(), "waymirror", "restore-token")
+
+
+def _load_restore_token():
+    try:
+        with open(_restore_token_path(), encoding="utf-8") as f:
+            return f.read().strip() or None
+    except OSError:
+        return None
+
+
+def _save_restore_token(token):
+    path = _restore_token_path()
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(token)
+    except OSError as e:
+        log.warning("could not save restore token: %s", e)
+
+
+class WayMirrorApp(Gtk.Application):
+    def __init__(self, geometry, half, show_cursor):
+        # NON_UNIQUE so several windows (different regions) can coexist.
+        super().__init__(
+            application_id=APP_ID,
+            flags=Gio.ApplicationFlags.NON_UNIQUE,
+        )
+        self.geometry = geometry  # (w, h, x, y) or None
+        self.half = half  # "left"/"right", resolved once monitor size is known
+        self.show_cursor = show_cursor
+        self.window = None
+        self.picture = None
+        self.pipeline = None
+        self.portal = None
+        # target display size (logical px), known once we have the region; keeps
+        # the window the right shape (see _on_compute_size).
+        self.desired_w = None
+        self.desired_h = None
+
+    # -- lifecycle --------------------------------------------------------
+    def do_activate(self):
+        if self.window:
+            self.window.present()
+            return
+
+        self.picture = Gtk.Picture()
+        # COVER fills the whole window keeping aspect, so there are never any
+        # letterbox bars; with the aspect-locked window below, the cropped-off
+        # sliver is sub-pixel.
+        self.picture.set_content_fit(Gtk.ContentFit.COVER)
+        self.picture.set_can_shrink(True)
+
+        self.window = Gtk.ApplicationWindow(application=self)
+        self.window.set_decorated(False)  # no title bar / window chrome
+        self.window.set_child(self.picture)
+
+        keys = Gtk.EventControllerKey()
+        keys.connect("key-pressed", self._on_key)
+        self.window.add_controller(keys)
+
+        # keep the window locked to the content's aspect ratio: when GNOME caps
+        # the height to the work area (top bar), shrink the width to match.
+        self.window.connect("realize", self._on_window_realize)
+
+        # the window is shown from _on_stream_ready, once we know the region
+        # size (left/right need the monitor size).
+        GLib.unix_signal_add(GLib.PRIORITY_DEFAULT, 2, self._quit)   # SIGINT
+        GLib.unix_signal_add(GLib.PRIORITY_DEFAULT, 15, self._quit)  # SIGTERM
+
+        bus = Gio.bus_get_sync(Gio.BusType.SESSION, None)
+        cursor_mode = CURSOR_MODE_EMBEDDED if self.show_cursor else CURSOR_MODE_HIDDEN
+        self.portal = PortalScreenCast(
+            bus, cursor_mode, self._on_stream_ready, self._on_portal_error,
+            restore_token=_load_restore_token(), save_token=_save_restore_token,
+        )
+        self.portal.start()
+
+    def do_shutdown(self):
+        if self.pipeline:
+            self.pipeline.set_state(Gst.State.NULL)
+        Gtk.Application.do_shutdown(self)
+
+    # -- window sizing ----------------------------------------------------
+    def _set_target(self, w, h):
+        self.desired_w = w
+        self.desired_h = h
+
+    def _present_window(self):
+        if self.geometry:
+            w, h, x, y = self.geometry
+            self.window.set_title(f"waymirror {w}x{h}+{x}+{y}")
+        else:
+            self.window.set_title("waymirror")
+        if self.desired_w and self.desired_h:
+            self.window.set_default_size(self.desired_w, self.desired_h)
+        else:
+            self.window.set_default_size(960, 540)
+        self.window.present()
+
+    def _on_window_realize(self, widget):
+        surface = widget.get_surface()  # GdkToplevel once realized
+        if surface is not None:
+            surface.connect("compute-size", self._on_compute_size)
+
+    def _on_compute_size(self, _toplevel, size):
+        if not self.desired_w or not self.desired_h:
+            return
+        bounds_w, bounds_h = size.get_bounds()
+        w, h = fit_within_bounds(self.desired_w, self.desired_h, bounds_w, bounds_h)
+        size.set_size(w, h)
+        log.debug("compute-size bounds=(%s,%s) -> %dx%d", bounds_w, bounds_h, w, h)
+
+    # -- input ------------------------------------------------------------
+    def _on_key(self, _controller, keyval, _keycode, _state):
+        if keyval in (Gdk.KEY_q, Gdk.KEY_Q, Gdk.KEY_Escape):
+            self.quit()
+            return True
+        return False
+
+    def _quit(self, *_):
+        self.quit()
+        return GLib.SOURCE_REMOVE
+
+    # -- stream -----------------------------------------------------------
+    def _on_portal_error(self, message):
+        log.error("%s", message)
+        self.quit()
+
+    def _on_stream_ready(self, fd, node_id, monitor_rect):
+        log.debug("streaming node %s (fd %s), monitor=%s", node_id, fd, monitor_rect)
+
+        # resolve left/right into a concrete region now that we know the monitor
+        if self.half:
+            if not monitor_rect:
+                self._on_portal_error(
+                    "portal did not report monitor size; use WxH+X+Y "
+                    "instead of left/right"
+                )
+                return
+            self.geometry = resolve_half(self.half, monitor_rect)
+
+        # pick the display target (logical size) and show the window
+        if self.geometry:
+            self._set_target(self.geometry[0], self.geometry[1])
+        elif monitor_rect:
+            self._set_target(monitor_rect[2], monitor_rect[3])
+        self._present_window()
+
+        self.pipeline = Gst.Pipeline.new("waymirror")
+        src = Gst.ElementFactory.make("pipewiresrc")
+        src.set_property("fd", fd)
+        src.set_property("path", str(node_id))
+        conv = Gst.ElementFactory.make("videoconvert")
+        crop = Gst.ElementFactory.make("videocrop")
+        # gtk4paintablesink negotiates GPU memory (DMABuf/GLMemory), but
+        # videocrop can only crop raw system-memory frames -- force that here.
+        rawfilter = Gst.ElementFactory.make("capsfilter")
+        rawfilter.set_property("caps", Gst.Caps.from_string("video/x-raw"))
+        sink = Gst.ElementFactory.make("gtk4paintablesink")
+        for el in (src, conv, crop, rawfilter, sink):
+            self.pipeline.add(el)
+        src.link(conv)
+        conv.link(crop)
+        crop.link(rawfilter)
+        rawfilter.link(sink)
+
+        self.picture.set_paintable(sink.get_property("paintable"))
+
+        # crop must be computed from the *negotiated* buffer size (HiDPI aware),
+        # so wait for caps on the cropper's sink pad, then set it once.
+        if self.geometry:
+            crop_pad = crop.get_static_pad("sink")
+            crop_pad.add_probe(
+                Gst.PadProbeType.EVENT_DOWNSTREAM,
+                self._configure_crop, crop, monitor_rect,
+            )
+
+        bus = self.pipeline.get_bus()
+        bus.add_signal_watch()
+        bus.connect("message::error", self._on_gst_error)
+        bus.connect("message::eos", lambda *_: self._quit())
+
+        self.pipeline.set_state(Gst.State.PLAYING)
+
+    def _configure_crop(self, pad, info, crop, monitor_rect):
+        event = info.get_event()
+        if event.type != Gst.EventType.CAPS:
+            return Gst.PadProbeReturn.OK
+        s = event.parse_caps().get_structure(0)
+        ok_w, cw = s.get_int("width")
+        ok_h, ch = s.get_int("height")
+        if not (ok_w and ok_h):
+            return Gst.PadProbeReturn.OK
+
+        left, top, right, bottom = compute_crop(cw, ch, monitor_rect, self.geometry)
+        crop.set_property("left", left)
+        crop.set_property("top", top)
+        crop.set_property("right", right)
+        crop.set_property("bottom", bottom)
+        log.debug(
+            "buffer %dx%d, crop l=%d t=%d r=%d b=%d", cw, ch, left, top, right, bottom
+        )
+        return Gst.PadProbeReturn.REMOVE
+
+    def _on_gst_error(self, _bus, message):
+        err, debug = message.parse_error()
+        log.error("gstreamer error: %s", err.message)
+        if debug:
+            log.debug("%s", debug)
+        self.quit()