Skip to content

About

Wayland/Hyprland fork of obs-zoom-to-mouse - zoom an OBS PipeWire screen capture to follow your cursor

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 

Repository files navigation

OBS Zoom to Mouse - Wayland / Hyprland

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.


Why this fork exists

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.

Requirements

  • OBS Studio (tested on 32.0.4; should work on 28+)
  • A Wayland session with Hyprland - the cursor position is read via hyprctl, so hyprctl must be on your PATH (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.


Install

  1. Save obs-zoom-to-mouse-wayland.lua somewhere permanent.
  2. In OBS, add a Screen Capture (PipeWire) source to your scene (if you don't have one).
  3. Open Tools -> Scripts.
  4. Press + and add obs-zoom-to-mouse-wayland.lua.

Setup

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.

  1. In the script settings, enable Allow any zoom source.

  2. Pick your Screen Capture (PipeWire) source as the Zoom Source (hit Refresh zoom sources if it isn't listed).

  3. 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 (the at XxY position of the monitor)
    Width / Height 2560 / 1440
    Scale X / Scale Y 1 / 1
    Monitor Width / Height 2560 / 1440
  4. 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)
  5. 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.


Settings reference

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.

Other compositors

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_seats or use a small helper
  • KDE/GNOME: a tool like ydotool or 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.


How tracking works

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.


Credits

The original code is (c) BlankSourceCode. This fork is shared in the same spirit for the Wayland/Hyprland community.

About

Wayland/Hyprland fork of obs-zoom-to-mouse - zoom an OBS PipeWire screen capture to follow your cursor

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages