Screeny

Mirror whichever screen you're working on onto a virtual display, so you can share one display in Google Meet/Zoom/Discord/etc...

Share the virtual display once. Move to another monitor and the shared view changes on-the-fly. Move back and it changes again. Others see a single stable screen the whole time. See how it works for more details!

Why I built This

I faced an issue when screen sharing with any software that supports it (Such as: Google Meet, Zoom, Discord, etc...) with multiple monitors, I'd often need to reference content on a different screen than the one I was sharing. This meant constantly switching which screen to share, or dragging windows between monitors.

Requirements

• Windows 10/11, 64-bit, or macOS 12+ (Linux is not supported yet.)
• Python 3.10+ (no third-party packages, everything written via ctypes)
• Windows only: Virtual Display Driver (Screeny can install one for you)

Installation

git clone https://github.com/zRakan/Screeny.git
cd Screeny

That's enough to run it, there is nothing to build and nothing to install. Every command below works straight from the source tree.

If you'd rather type screeny than python -m screeny, install it into your environment, this only adds the launcher, no dependencies come with it:

pip install -e .        # then: screeny doctor, screeny vdd install, ...

Quick start

Initially, you need to setup the Virtual Display Driver:

• Windows: python -m screeny vdd install (needs elevated user).
• macOS: Already Screeny creates its own virtual display at start-up (via CGVirtualDisplay API). It will ask for the Screen Recording permission.

After that, you could do:

# 1. Check everything is wired up
python -m screeny doctor

# 2. Run it
python -m screeny

In Meet/Zoom/Discord, share the virtual screen. If you faced an issue, check Troubleshooting section.

No virtual display yet, or just want to see it work?

Use the windowed preview:

python -m screeny --windowed

Screen Recording permission (macOS)

The first run needs the Screen Recording permission:

System Settings > Privacy & Security > Screen Recording

Grant it to whichever app is actually running the process (Terminal, iTerm, ...) then restart that app once.

Hotkeys (Customizable)

Hotkey	What it does
Ctrl+Alt+Shift+F	Freeze the mirror to the current screen and stop following
Ctrl+Alt+Shift+B	Hide the shared screen behind a placeholder
Ctrl+Alt+Shift+Q	Quit, and disable the virtual display
Ctrl+Alt+Shift+K	Quit but keep the virtual display attached (not always present, see why)

You can customize them in Screeny's config.json. macOS shows the same hotkeys as ⌃⌥⇧F and friends.

If a hotkey is misspelled, or another app already owns it, Screeny falls back to the built-in default for that action rather than leaving you without the control, and tells you it did (more details).

Tray

Screeny lives in the system tray (taskbar, or the menu bar on macOS). You can see the state of Screeny. The list of all states:

Icon	State	Meaning
🟦 blue, screen outline	following	Mirroring whichever screen your cursor is on
🟥 red, pause bars	frozen	Pinned to one screen, not following you
⬛ grey, single bar	blanked	Viewers see a placeholder, not your screen

Additionally, you can see more options by right-click Screeny's tray icon.

How it decides what to mirror

By default Screeny follows the monitor your mouse cursor is on (--follow mouse), with a 250 ms debounce so that dragging the cursor across a monitor edge to reach a window on the far side doesn't strobe the shared view.

• Additional following modes:
  • --follow focus switches on the focused screen instead (When user clicks on the screen)
  • --follow manual never switches on its own, you pick from the tray or freeze on a screen.

Closing modes

Screeny has different exit modes based on the scenario:

Scenario	Available modes
Elevated, or vdd helper installed	Exit with/without closing Virtual Display
Not elevated and no helper tasks	Exit without closing Virtual Display
keep_display_on_exit / --keep-display-on-exit	Exit without closing Virtual Display
manage_virtual_display: false, or --windowed	Exit without closing Virtual Display
macOS (The display can't outlive the process)	Exit without closing Virtual Display

Documentation

Page	What's in it
Configuration	Settings and CLI overrides
Virtual Display	Windows driver, helper tasks, removal
Troubleshooting	Common issues with their solutions
How it works	How Screeny works and its limitations

Contributing

Issues and pull requests are welcome. Just clone it and run python -m screeny.

Please when reporting a bug, paste the output of:

python -m screeny doctor

It prints the:

• Environment (Python version, OS version, etc...).
• Every display with its adapter/monitor/PnP identity.
• Which display Screeny would present on and which it would mirror.
• Hotkey availability.
• Capture benchmark.

Acknowledgements

• Special thanks to the team behind VDD (Virtual Display Driver) for improving the driver and maintain it.
• Microsoft Windows GDI (Graphics Device Interface) for providing information about how to interact with the API.
• Mcrosoft Windows Drivers for providing documentations/guides in how driver management works.