Configuring StreamUP Source Zoom
by Andi
Version: 0.0.1
Zoom into your mouse cursor with a hotkey, across every canvas at once. Press the key and your display capture eases in on wherever the pointer is. Press it again and it eases back out.
The bit that makes it different is the "every canvas" part. Point it at the display capture in your main 16:9 scene and the display capture in your Aitum Vertical 9:16 scene, hit one hotkey, and both zoom into the same spot at the same time. Each canvas keeps its own framing, so you're not fighting aspect ratios or setting the same thing up twice.
Requires OBS 31.1.0 or newer. Cursor tracking and monitor mapping are Windows-only. It builds and loads on macOS and Linux, but it won't follow the cursor there.
How It Works
It isn't a source filter. It's a controller that sits in the frontend and, when you hit the hotkey, takes the scene item for each source you've listed and adjusts its crop and transform to frame a window around your cursor.
Because it works from the framing each item already has, the maths stays aspect correct on landscape and vertical with no per-canvas fiddling. At rest it reproduces exactly the shot you already had. As you zoom in, the pan is clamped to the whole source rather than the visible part, so a wide capture that hangs off the edge of a vertical canvas can still pan out to its own left and right edges.
If OBS closes or crashes while you're zoomed, the true framing is stashed on the scene item and put back on the next launch. You don't end up with a zoom baked into your scene.
Setting It Up
Open Tools → StreamUP Source Zoom Settings. The window has three tabs: Sources, Behaviour and Hotkeys.
- On the Sources tab, press Add Source
- Press Edit on the new row to open that source in its own window
- Fill in what it zooms (below), then press Done
- Set your hotkeys on the Hotkeys tab
- Add a second source for your vertical canvas if you have one
The Sources list is one line per source: a tick to include it, a summary of what it zooms, and an Edit button. Everything else is edited in the source's own window.
Zoom Source
The first tab of a source's window. Which source it zooms, and how far in it goes.
- Zoom this source includes it when you zoom. Untick to leave it alone without deleting the row.
- Canvas is which canvas the scene lives on. Aitum Vertical has its own canvas here.
- Scene is the scene that contains the source. Only scenes on the chosen canvas are listed.
- Source is the display capture to zoom. Only sources on the chosen scene are listed.
- Monitor is which physical monitor that source captures, so the cursor lines up with the zoom. The Auto button works it out from the display capture source itself.
- Zoom amount is how far this canvas zooms in, from
1.0to10.0.2.0shows half the screen,4.0shows a quarter.
Timing, smoothing and the main hotkeys are shared by every source and live on the Behaviour and Hotkeys tabs.
TIP
If the display capture's resolution matches the monitor's resolution, the cursor mapping is one to one, which is the normal case.
See Through
The second tab of a source's window. While you're zoomed, anything sat over the spot you're pointing at fades down so you can read what's behind it. Move the cursor under your camera and the camera goes see-through until you move away again.
It's off by default, because it touches your sources: it works by putting a colour-correction filter on the source and riding its opacity. The filter comes back off on its own once the source returns to full, so nothing's left behind.
- Fade sources sat under the cursor turns it on for this source.
- Fade to is how far down it fades, in percent.
0 %is invisible. Default is30 %. - Start within is how near the cursor has to get before a source starts fading, in canvas pixels measured from its edge. It ramps across that distance, so the source is out of the way by the time you arrive. Set it to
0to only fade once the cursor is actually over the source. Default is200 px. - Fade time is how long the fade takes, in seconds. Default is
0.15 s. - Even when not zoomed runs it all the time, so a source goes see-through whenever the cursor is behind it, zoom or no zoom.
These are set per source, not globally, because how far a camera should fade and how near you have to get depends on the shot you're zooming.
Each source over the top is measured against the pointer on its own, so a camera in one corner and an alert box in the other fade independently. Sources tucked inside nested scenes or groups are measured where they're actually drawn, and downstream keyer layers fade too. Fading only happens on a scene that's actually on screen, so a source used in several scenes won't fade in all of them at once.
Sources Placed by Hand
Most setups need none of this. Skip it unless you have a source that's masked or cropped by a filter.
If a source is cropped by a filter, an Advanced Mask say, its scene item box still covers the whole canvas and OBS has no idea the picture is really a small circle in the corner. Without help, the pointer counts as behind it everywhere.
The bottom of the See Through tab has a live preview of your canvas. Pick a source, press Add, and drag a box over where it really appears. The source's own box shows as an amber dashed outline to line up against, and Fit to source fills the box from it, which is the right answer outright for anything that isn't masked.
Each region can apply to Any zoom target or to just one, for when the overlay sits differently depending on which source you zoom.
Behaviour
Shared by every source.
Toggle Mode
- Follow cursor tracks the cursor while you're zoomed.
- Snap & hold jumps to wherever the cursor was when you toggled, then stays put.
Motion
- Easing curve is the shape of the zoom motion: Linear, Smooth, Ease in, Ease out, or Ease in-out. Smooth eases both ends.
- Zoom-in time and Zoom-out time are how long each direction takes, in seconds. Set them differently if the two feel uneven.
- Cursor smoothing is how much the cursor tracking is smoothed, in seconds. Higher glides more, which helps if the zoom makes people queasy.
- Update rate (Hz) is how often the zoom updates per second, from
30to240. Match or beat your recording frame rate for the smoothest result.
Framing
- Deadzone is how far from the centre of the screen the cursor can move without panning, as a fraction of the way from centre to edge. Small movements near the middle keep a steady shot instead of jittering.
0pans with the cursor exactly. - Edge push reaches the full pan before the cursor gets all the way to the screen edge, so edge content is easy to frame without pixel-perfect pointing.
- Follow active monitor only zooms the source on the monitor the cursor is currently on. Useful on a multi-monitor setup where you only want the display you're pointing at to move.
Scroll to Zoom
Change the zoom depth live with the mouse wheel while you're zoomed. Windows only.
- Scroll to zoom turns it on. On by default.
- Wheel step is how much the zoom changes per notch.
- Wheel smoothing is how long the depth takes to glide to where the wheel asked for. Notches roll into one continuous move rather than a stack of little steps. Default
0.22 s; set it to0to snap straight there. - Max zoom is the ceiling for the zoom depth, including scroll-to-zoom.
- Remember zoom depth keeps whatever depth you last dialled in with the wheel, so zooming out and back in returns to the same place. Turn it off to reset to the configured factor each time.
Hotkeys
Set them on the Hotkeys tab or in Settings → Hotkeys in OBS. Both stay in sync.
| Hotkey | What it does |
|---|---|
| Toggle zoom | Press once to zoom in, again to zoom out |
| Hold to zoom | Zoomed while held, back to normal on release. Always follows the cursor |
| Zoom: source name | Zooms just that one source. One is registered per enabled source |
| Scroll-zoom hold | Optional. While this key is held the wheel controls zoom depth and is swallowed; otherwise the wheel passes through so normal scrolling still works |
The zoom hotkeys keep working while an OBS dialog has the keyboard, so you can zoom in and read something while Settings or a source's properties are open. A bare key with no modifier stands down while you're typing into a field, so naming a source can't toggle your zoom by accident.
WebSocket API
Registered under the streamup-source-zoom vendor. Send a CallVendorRequest with vendorName set to that, and anything that speaks obs-websocket, a Stream Deck, a chat command or a Streamer.Bot action, can drive the zoom.
| Request | Fields | What it does |
|---|---|---|
ToggleZoom | – | Flips the global zoom on or off |
ZoomIn / ZoomOut | – | Forces it on or off. Zooming out also clears a pinned point |
SetZoom | enabled | The same, as a single request |
ZoomSource | sourceName or targetIndex, optional sceneName, state (on/off/toggle) | Zooms one source on its own, like that source's own hotkey |
SetZoomLevel | level, optional relative | Sets the live depth. level: 3 is 3x; with relative: true it's a nudge. Same clamps as the scroll wheel |
ResetZoomLevel | – | Drops the live depth back to each source's configured zoom amount |
SetZoomFactor | target + zoomFactor | Changes a source's configured zoom amount and saves it |
SetTargetEnabled | target + state | Enables or disables a source |
SetZoomMode | mode (follow/snap/toggle) | Sets the zoom mode. toggle is not a third mode, it swaps whichever of the two is current |
ZoomToPoint | x, y, optional monitorIndex, normalized, level, engage | Frames a fixed screen point instead of the cursor. With monitorIndex the coordinates are relative to that monitor; with normalized: true they're 0–1 fractions of it |
ClearZoomPoint | – | Hands framing back to the cursor |
GetZoomState | – | Reads the whole state back |
Every request replies with success plus the same state block: zoomed, zoomLevel, mode, pinned, and a targets array carrying each source's scene, source, monitor, zoom factor and its own zoom state.
The plugin also emits a ZoomStateChanged vendor event whenever any of that changes, including when you drive it from the keyboard or the scroll wheel, so a Stream Deck key can stay in sync without polling.
INFO
The absolute level is measured against the largest configured zoom factor, since the live depth is shared across every source.
Good to Know
- Windows only for the cursor. Live cursor tracking and monitor mapping need Windows. It compiles and loads elsewhere, but it won't follow the pointer.
- It never bakes a zoom into your scene. The real framing is stashed on the scene item, so a crash or a close while zoomed doesn't leave your source cropped.
- See-through is per source and off by default. It puts a colour-correction filter on the sources it fades and takes it off again when they return to full.
- One row per canvas. Main and vertical are two rows pointing at two different display captures, not one row doing double duty.
- Settings are saved in the module config directory, not in your scene collection, so they follow the plugin rather than the scenes.