Add a ScreenCaptureKit backend for macOS

[jholveck]

The macOS docs and headers indicate that CGWindowListCreateImage, the screenshot mechanism MSS uses on macOS, is now deprecated. Apple suggests using the new (as of 2022) ScreenCaptureKit instead.

I don't know offhand how widely-available ScreenCaptureKit is; it might not exist prior to macOS 13 Ventura. It also seems that the early versions were geared for streaming, not single-frame capture. Later versions added a screenshot-style API; there's some talk about the migration path in this talk.

Practically speaking, I doubt that macOS will remove CGWindowListCreateImage anytime soon; it's just too widely-used. So no urgency here.

[m13v]

we maintain a ScreenCaptureKit-based recording SDK for macOS and can confirm the migration path from CGWindowListCreateImage is doable but has some sharp edges.

SCK has two capture modes relevant here: SCStream for continuous frame delivery (streaming) and captureImage (added in macOS 14) for single-frame screenshot capture. for a library like mss that does single-frame grabs, captureImage is the right API. it's essentially a drop-in replacement for CGWindowListCreateImage but async. the returned CGImage has the same pixel format and coordinate system.

the main complexity is that SCK requires you to first enumerate available content via SCShareableContent, then create an SCContentFilter, then capture. that's 3 async calls where CGWindowListCreateImage was 1 sync call. for Python bindings, wrapping this in a synchronous function that blocks on the async result is probably the pragmatic approach.

version availability: SCShareableContent and SCStream landed in macOS 12.3, captureImage for single screenshots in macOS 14. so you'd want a fallback path that uses the old CGWindowListCreateImage for macOS 12 and 13, switching to SCK on 14+.

biggest gotcha: SCK requires Screen Recording TCC permission for any capture, including screenshots. CGWindowListCreateImage only needed it for capturing other apps' content, not your own windows. so migrating to SCK may trigger a new permission prompt that users didn't see before. worth documenting that behavior change.

[m13v]

our ScreenCaptureKit implementation as reference for the SCShareableContent enumeration, SCContentFilter setup, and async capture pattern: https://github.com/m13v/macos-session-replay/blob/main/Sources/SessionReplay/ScreenCaptureService.swift

it's Swift but the API surface maps directly to PyObjC bindings. shows the permission preflight checks, content enumeration, and frame delivery delegate pattern.