Building for multiple displays was harder than we thought

LumaSpace looked great on a single screen from day one. Then someone plugged in a second monitor and everything broke. We're a Mac-only studio, and plenty of the people who want a video wallpaper run more than one display — and they don't arrange those displays the way you'd expect.

The naive approach

Our first version just set the same wallpaper on every screen. This sort of worked, but a vertical 4K monitor next to a widescreen ultrawide meant the video got stretched on one or cropped on the other. It looked terrible. The whole point of the app is cinematic 4K scenes that look composed, not smeared, so shipping one buffer to every panel was never going to hold.

Per-screen, per-resolution

The fix sounds simple: let each screen have its own wallpaper at its own resolution. In practice this meant:

• Detecting when screens connect and disconnect (Macs are hot-plug, so this happens constantly with docks).
• Remembering which wallpaper was on which screen, even when the screen arrangement changes.
• Handling the case where someone unplugs a monitor, rearranges their desk, and plugs it back in a week later.
• Not crashing when a virtual display (like Sidecar or AirPlay) appears and disappears.
• Surviving sleep and wake, which on a multi-monitor setup is a small storm of connect and disconnect events fired in no guaranteed order.

Each of these sounds like a small edge case. Together they took almost two months to get right. Most of that time went not into the happy path but into the moments where macOS hands you the same display twice, or in a different order, or briefly not at all.

The screen identity problem

macOS identifies screens by a combination of vendor ID, model, and serial number. Except some monitors don't report serial numbers. And some USB-C docks present as a different display device depending on which port you use. A laptop lid that opens to a known docking station is a different proposition from the same laptop opened on a train, and the system does not always tell them apart for you.

We ended up using a combination of the display ID, resolution, and physical position to create a "best guess" identifier. It works about 95% of the time. For the other 5%, there's a manual override in the menu bar: pick the screen, pick the scene, and we remember it. Not glamorous, but it means the rare edge case is a two-second fix rather than a wallpaper that mysteriously won't stick.

More screens, not more battery

Driving a different 4K scene on every display sounds like it should punish a laptop. It doesn't, because the renderer only does work for screens you can actually see — a monitor sitting behind a maximized window, or one you've turned away from, costs almost nothing. The full story of how that works is its own post: why LumaSpace uses so little battery.

Why we bothered

Nobody has complained about their wallpaper disappearing when they plug in a second monitor since we shipped this, and that's the kind of problem we like solving. It's invisible when it works, which is exactly the point: the displays come and go, the desk gets rearranged, the laptop sleeps and wakes, and the right scene is simply there on the right screen. We're a small, bootstrapped studio, and this is the sort of unglamorous correctness we'd rather spend two months on than skip.