Dynamic zoom and mouse tracking for any video source in OBS.
Zoom into any part of your screen during recordings or live streams — with smooth animations, mouse follow, and multi-monitor support.
Note — This is a third-party community script. It is not developed, maintained, or endorsed by the OBS Project.
| Feature | Description |
|---|---|
| Smooth Zoom | Animated zoom-in/out with configurable duration (instant to cinematic) |
| Mouse Follow | Viewport tracks the mouse with adjustable smoothing — via the Follow hotkey or the optional Auto-follow mode |
| Works with any source | Capability-based detection: any video source is supported (screen/display/window/game capture, browser, media…) on every OS and OBS version |
| Nested scenes & groups | Drills down to the original capture source inside nested scenes and groups; optional Preferred Source picker |
| HiDPI / Retina aware | Correct tracking on high-DPI displays and scaled desktops, not just 1:1 monitors |
| Multi-Monitor | Automatic monitor detection and correct coordinate mapping |
| Anti-Flicker | Deadzone and threshold system eliminates visual jitter |
| Hotkey Driven | Toggle zoom and follow independently via OBS hotkeys |
| Scene Aware | Smooth transitions when switching scenes while zoomed |
| Debug Mode | Detailed logging for troubleshooting |
- Download
zoom-follow-mouse-and-more-eg.lua. Use one of these so you get the script, not a web page:- Releases (recommended): grab the
.luaasset from the latest release, or - Raw link: open the raw file → right-click → Save As… (keep the
.luaextension).
- Releases (recommended): grab the
- In OBS: Tools > Scripts > "+" and select the file
⚠️ Don't use File → Save Page As on the GitHub code viewer — that saves an HTML page and OBS will reportError loading file: ... unexpected symbol near '<'. Always use the Releases asset or the Raw link above.
Go to File > Settings > Hotkeys and assign keys for:
- Toggle Zoom — activates/deactivates zoom
- Toggle Follow — the viewport follows the mouse while zoomed in
Important — Select your source and press Ctrl+F (Fit to Screen) before activating zoom. This ensures accurate mouse-to-crop mapping.
Press your zoom hotkey to zoom in at the mouse position. Press again to zoom out. Toggle follow to have the viewport track the mouse while zoomed.
| Setting | Range | Default | What it does |
|---|---|---|---|
| Zoom Value | 1.1 – 100 | 2.0 | Zoom multiplier. Quality depends on source resolution. |
| Zoom In Duration | 1 – 60 000 ms | 300 ms | Animation length for zooming in. Set to 1 for instant. |
| Zoom Out Duration | 1 – 60 000 ms | 500 ms | Animation length for zooming out. Set to 1 for instant. |
| Follow Speed | 0.01 – 1.0 | 1.0 | How fast the viewport tracks the mouse. 1.0 = instant, 0.1 = smooth glide. |
| Auto-follow while zoomed | on/off | off | When on, the viewport follows the mouse as soon as you zoom in — no separate hotkey needed. The Follow hotkey still works as a freeze/unfreeze toggle. |
| Preferred Source (optional) | source name | (automatic) | Pin which source to zoom by name. Leave empty to auto-pick the first capture found (drilling into nested scenes and groups). |
| Debug Mode | on/off | off | Enables detailed logging in OBS Script Logs. |
Tip — If you just want "zoom and it follows", turn on Auto-follow while zoomed and you can ignore the Follow hotkey entirely.
Tip — For tutorials and coding, use Follow Speed
1.0(instant tracking). For presentations and gameplay, try0.1–0.3for a smooth camera feel.
Click to expand advanced settings
| Setting | Range | Default | What it does |
|---|---|---|---|
| Update Interval | 8 – 100 ms | 16 ms | Tick rate. 16 ms ≈ 60 fps, 8 ms ≈ 120 fps. |
| Mouse Cache Duration | 4 – 32 ms | 8 ms | How long to cache mouse position (reduces FFI calls). |
| Setting | Range | Default | What it does |
|---|---|---|---|
| Mouse Deadzone | 1 – 10 px | 3 px | Minimum mouse movement to trigger a viewport update. |
| Crop Update Threshold | 1 – 10 px | 2 px | Minimum crop change to apply. Prevents micro-jitter. |
| Crop Edge Threshold | 1 – 20 px | 5 px | Increased threshold at screen edges/corners. |
| Setting | Range | Default | What it does |
|---|---|---|---|
| Scene Transition Duration | 100 – 1000 ms | 300 ms | Smoothness of crop transitions during scene changes. |
| Default Monitor Width | 640 – 7680 | 1920 | Fallback if monitor detection fails. |
| Default Monitor Height | 480 – 4320 | 1080 | Fallback if monitor detection fails. |
| Problem | Solution |
|---|---|
Error loading file: ... unexpected symbol near '<' |
You saved the GitHub HTML page instead of the script. Re-download from Releases or the Raw link (see Install). |
| Zoom doesn't activate | Check source has valid dimensions. Press Ctrl+F on source first. |
| Zoom centers but doesn't follow the mouse | Follow is a separate action: press the Toggle Follow hotkey, or enable Auto-follow while zoomed in settings. (On high-DPI/Retina displays tracking is fixed in 2.2.0.) |
| Zoom always jumps to the top-left corner (Linux) | Fixed in 2.2.1 — the Linux cursor code failed to initialise, so the mouse always read (0,0). Update to 2.2.1. |
| Zoom goes to the centre and follow is disabled (Linux) | You're on a Wayland session; the global cursor position is unreadable there. Use an Xorg session for follow — see Platform support. |
| Hotkeys only work when OBS is focused (Linux) | OBS core limitation on Wayland — see Platform support for workarounds. |
| Flickering at edges | Increase Crop Edge Threshold or Mouse Deadzone in Advanced Settings. |
| Follow feels laggy | Lower Update Interval (e.g. 8 ms) and/or lower Mouse Deadzone. |
| Mouse escapes viewport at high zoom | Normal at extreme zoom levels (tiny viewport). Lower Update Interval helps. |
| Source appears to resize | Press Ctrl+F to fit source to screen before activating zoom. |
| No valid video source | Ensure the active scene contains a video source. Captures inside nested scenes and groups are supported; if several captures exist, set a Preferred Source. |
| Wrong source gets zoomed | Set Preferred Source to the exact source name you want. |
Still stuck? Enable Debug Mode, reproduce the issue, then check Tools > Scripts > Script Logs.
Since v2.2.0 the script detects sources by capability — any source that produces video can be zoomed, regardless of its internal type ID. It also drills into nested scenes and groups to find the original capture. The table below lists common, tested capture types per platform; it is not exhaustive.
| Platform | Common capture types |
|---|---|
| Windows | Display Capture, Window Capture, Game Capture |
| macOS | Display Capture, macOS Screen Capture (ScreenCaptureKit) |
| Linux | Screen/Window Capture (PipeWire / Wayland), XSHM, Xcomposite |
| Any | Browser, Media/VLC, Image, and other video sources |
If a scene contains several video sources (e.g. a webcam overlay plus a screen capture), the script prefers a known capture source. Use Preferred Source to override the choice.
Zooming works everywhere. Mouse tracking (mouse-centred zoom + follow) needs the OS to expose the global cursor position:
| Session | Mouse-centred zoom | Follow |
|---|---|---|
| Windows | ✅ | ✅ |
| macOS | ✅ | ✅ |
| Linux — Xorg / X11 (incl. GNOME on Xorg) | ✅ | ✅ |
| Linux — Wayland | ❌ zooms to source centre | ❌ disabled |
Wayland deliberately provides no protocol for an application to read the global cursor position — a client only receives pointer coordinates while the cursor is over its own window. Under XWayland, XQueryPointer reports the real position only while the cursor is over an X11 surface, never over the native Wayland desktop you are capturing. This affects every OBS zoom script, not just this one.
Since v2.2.1 the script detects Wayland, says so in the Script Log and in the script properties, disables follow, and zooms to the centre of the source rather than silently jumping into a corner. For mouse-centred zoom and follow, log in to an Xorg session (on GDM: click the ⚙ gear on the login screen → GNOME on Xorg).
This is an OBS core limitation on Wayland — OBS does not implement the XDG GlobalShortcuts portal (obs-studio#10538) — and no script can change it. Options:
- Community plugins implement the portal for OBS, e.g. WaylandHotkeys (Flatpak:
com.obsproject.Studio.Plugin.WaylandHotkeys) or obs-wayland-hotkeys. They register the hotkeys returned byobs_enum_hotkeysand need a recent Qt plus GNOME 49+ / KDE Plasma 6+.Untested: their documentation describes OBS's built-in actions. Whether hotkeys registered by scripts (this script's Toggle Zoom / Toggle Follow) are exposed is not documented — if you try it, please report back.
- obs-websocket: bind a desktop-level shortcut to
obs-cmd/obs-cli. This works regardless of how the hotkey was registered.
We need volunteers to test on Linux and macOS. If you can help:
- Test with different OBS versions
- Report platform-specific bugs
- Share your OS, OBS version, and script logs
Open an issue or contact the author — any feedback is appreciated.
- OBS Studio 30.0.0 or higher
- Lua 5.1 or higher (bundled with OBS)
Found a bug or have a feature idea? Open an issue with:
- Steps to reproduce
- OBS version and OS
- Script logs (Debug Mode enabled)
GNU General Public License v3.0
Edoardo Guzzi — @mredodos
Inspired by the OBS community's zoom and follow scripts, with multi-monitor support and smooth animations built from the ground up.