An OBS Lua script that zooms a screen-capture source to focus on the mouse, working on Wayland (tested on Hyprland).
This is a Wayland-friendly fork of BlankSourceCode/obs-zoom-to-mouse. All the credit for the original idea, the zoom/follow animation, and the bulk of the code goes to them - this fork just makes it actually work on a modern Wayland desktop.
Great for screen recordings where you want to zoom into your IDE/terminal to highlight a section of code and have the camera follow your cursor.
The original script is built around X11. On Wayland (Hyprland, etc.) it silently fails in three ways, and this fork fixes each of them:
| Problem on Wayland | Fix in this fork |
|---|---|
The "Zoom Source" dropdown stays empty - the script only looks for the X11 xshm_input source. |
Detects the PipeWire screen-capture source (pipewire-screen-capture-source) when running in a Wayland session. |
Even when XWayland is running, XOpenDisplay succeeds but XQueryPointer returns a frozen/zero cursor, so the zoom locks to the top-left corner and never follows the mouse. |
On a Wayland session the script skips X11 entirely and reads the live cursor from hyprctl cursorpos on a background timer. |
On OBS 30+ the script crashes with attempt to call field 'obs_sceneitem_get_info' (a nil value). |
OBS renamed obs_sceneitem_get_info/set_info to the *_info2 variants; the script aliases the old names to the new ones, so it works on OBS 32.x and older versions. |
- OBS Studio (tested on 32.0.4; should work on 28+)
- A Wayland session with Hyprland - the cursor position is read via
hyprctl, sohyprctlmust be on yourPATH(it lives at/usr/bin/hyprctl) - A Screen Capture (PipeWire) source in your scene
Using a different Wayland compositor (sway, KDE, GNOME)? See Other compositors below - it's a one-line change.
- Save
obs-zoom-to-mouse-wayland.luasomewhere permanent. - In OBS, add a Screen Capture (PipeWire) source to your scene (if you don't have one).
- Open Tools -> Scripts.
- Press + and add
obs-zoom-to-mouse-wayland.lua.
Because PipeWire sources don't report their on-desktop geometry to OBS, you have to tell the script how big your monitor is. It's a one-time thing.
-
In the script settings, enable Allow any zoom source.
-
Pick your Screen Capture (PipeWire) source as the Zoom Source (hit Refresh zoom sources if it isn't listed).
-
Enable Set manual source position and fill in your monitor's values. Get them with:
hyprctl monitors
For a monitor reported as
2560x1440@144 at 0x0, use:Field Value X / Y 0/0(theat XxYposition of the monitor)Width / Height 2560/1440Scale X / Scale Y 1/1Monitor Width / Height 2560/1440 -
For best results, set the source's Transform to:
- Positional Alignment: Top Left
- Bounding Box Type: Scale to inner bounds
- Alignment in Bounding Box: Top Left
- Crop: all zeros (if you need to crop, use a Crop/Pad filter instead of a transform crop)
-
In File -> Settings -> Hotkeys, bind:
- Toggle zoom to mouse - zoom in / out
- Toggle follow mouse during zoom (optional) - turn cursor tracking on/off
Press your zoom hotkey and move your mouse - the view should zoom in and follow the cursor.
| Setting | What it does |
|---|---|
| Zoom Source | The screen-capture source to zoom. |
| Zoom Factor | How much to zoom in. |
| Zoom Speed | Speed of the zoom in/out animation. |
| Auto follow mouse | Track the cursor automatically while zoomed in. |
| Follow outside bounds | Keep tracking even when the cursor leaves the source bounds. |
| Follow Speed | How fast the zoomed view chases the cursor. |
| Follow Border | % distance from the edge that re-enables tracking after it locks. |
| Lock Sensitivity | How still the cursor must be before tracking locks into place. |
| Auto Lock on reverse direction | Stop tracking when you reverse mouse direction (RTS-style panning). |
| Allow any zoom source | Lets you pick non-display sources - required for PipeWire. |
| Set manual source position | Manually set source X/Y/size - required for PipeWire. |
The cursor is read by on_wayland_mouse_timer() via:
ffi.C.popen("/usr/bin/hyprctl cursorpos 2>/dev/null", "r")To use a different Wayland compositor, swap that command for one that prints x, y:
- sway / wlroots: parse
swaymsg -t get_seatsor use a small helper - KDE/GNOME: a tool like
ydotoolor a custom DBus query
The script already falls back to the cached value if the command fails, so an empty/garbage result just freezes the cursor rather than crashing.
When you press the zoom hotkey, the script uses the current mouse position as the center of the zoom and animates a crop/pad filter to zoom in. With Auto follow mouse on, it then keeps the cursor in view.
Once zoomed, you get a safe zone - move the cursor freely without the camera moving. When you push the cursor toward the edge (within Follow Border), it starts panning to follow you, and re-locks once you hold still (Lock Sensitivity). Auto Lock on reverse direction makes it stop the moment you head back toward center, like panning a camera in a strategy game.
- Original script & concept: BlankSourceCode/obs-zoom-to-mouse
- Inspired by tryptech's obs-zoom-and-follow
- Wayland / Hyprland fork: xevrion
The original code is (c) BlankSourceCode. This fork is shared in the same spirit for the Wayland/Hyprland community.