PyObjC ScreenCaptureKit Framework Bindings

Warnings

• breaking Python 3.9 support was dropped in PyObjC 12.0. PyObjC 11.0 also dropped support for Python 3.8. Ensure your Python version meets the `pyobjc` requirements (currently Python >=3.10).
  Fix: Upgrade your Python environment to 3.10 or later.
• breaking The core bridge's behavior for initializer methods (e.g., `init` family) was aligned with `clang`'s Automatic Reference Counting documentation. This change in object lifecycle management can cause subtle reference counting issues in existing code that relied on the previous PyObjC behavior.
  Fix: Review code involving object creation and initialization, especially where references are passed or returned, to ensure correct memory management under the new ARC semantics.
• gotcha Accessing ScreenCaptureKit functionalities requires explicit 'Screen Recording' permissions in macOS System Settings > Privacy & Security. Without this permission, API calls may return errors or empty results.
  Fix: Grant 'Screen Recording' permission to the Python application or terminal running the script in macOS System Settings.
• gotcha PyObjC, including `ScreenCaptureKit` bindings, is fundamentally a macOS-only library due to its reliance on Apple's Cocoa and Foundation frameworks. It will not run on other operating systems.
  Fix: Ensure the application is deployed and run exclusively on macOS environments.
• gotcha Free-threading (PEP 703) in Python 3.13 is experimentally supported as of PyObjC 11.0. Older versions (e.g., PyObjC 10.3) explicitly stated no support for it. While experimental support exists, be aware of potential instabilities or unexpected behavior when using PyObjC in a free-threaded Python environment.
  Fix: If encountering issues, consider using a non-free-threaded Python 3.13 build or a Python 3.12 environment until free-threading support in PyObjC matures.
• gotcha Many ScreenCaptureKit operations are asynchronous, relying on completion handlers or delegates. For these handlers to execute, the macOS `NSRunLoop` must be active. In simple scripts, you might need to manually run `objc.currentEventLoop().runUntilDate_(...)` to allow callbacks to process.
  Fix: Ensure the `NSRunLoop` is active when performing asynchronous operations, either by running an application's main loop or explicitly running `objc.currentEventLoop()` for a duration.

Install

• pip install pyobjc-framework-screencapturekit Install ScreenCaptureKit bindings

Imports

• ScreenCaptureKit

  import ScreenCaptureKit

• SCShareableContent

  from ScreenCaptureKit import SCShareableContent

Quickstart

This quickstart demonstrates how to list available screen capture content (applications, displays, windows) using `SCShareableContent`. Note that running this code requires 'Screen Recording' permissions to be granted to your Python environment in macOS System Settings > Privacy & Security. Asynchronous operations in `ScreenCaptureKit` require the `NSRunLoop` to be active for completion handlers to execute.

import ScreenCaptureKit
from Foundation import NSLog, NSDate
import objc

# Define a completion handler for the asynchronous call
def completion_handler(content, error):
    if error:
        NSLog("Error getting shareable content: %@", error)
    elif content:
        NSLog("Successfully retrieved shareable content:")
        NSLog("Applications: %s", content.applications())
        NSLog("Displays: %s", content.displays())
        NSLog("Windows: %s", content.windows())
    else:
        NSLog("No content or error.")

# Asynchronously get available screen capture content
# Note: This requires 'Screen Recording' permission in macOS System Settings.
ScreenCaptureKit.SCShareableContent.getShareableContentWithCompletionHandler_(completion_handler)

# Keep the runloop active briefly for the completion handler to execute.
# In a full Cocoa application, this would be handled by the app's main runloop.
objc.currentEventLoop().runUntilDate_(NSDate.dateWithTimeIntervalSinceNow_(2))