PyObjC MediaLibrary Framework

Warnings

• breaking PyObjC 12.0 dropped support for Python 3.9. Projects using older Python versions must upgrade to Python 3.10 or later to use `pyobjc-framework-medialibrary` 12.x. PyObjC 11.0 dropped Python 3.8 support.
  Fix: Ensure your Python environment is 3.10 or newer. Consider using Python 3.11 or later for the best compatibility and features.
• breaking PyObjC 11.1 introduced significant changes to how initializer methods (methods in the 'init' family) handle Automatic Reference Counting (ARC), aligning with `clang`'s documentation. This means such methods now correctly 'steal' a reference to `self` and return a new one, which might alter reference counting behavior in complex Objective-C/Python interactions.
  Fix: Review custom Objective-C classes exposed to Python via PyObjC, especially those with custom `init` methods, to ensure correct memory management under the new ARC behavior.
• gotcha Using `MLMediaLibrary` (and many other macOS frameworks) from a plain Python script executed from the command line can lead to `XPC connection interrupted` errors. These frameworks often expect to be run within a full macOS application bundle with specific entitlements.
  Fix: For production or robust usage, consider building your Python script into a macOS application bundle using `py2app` and ensuring proper entitlements are configured. For development, be aware that functionality may be limited or unreliable outside an app context.
• gotcha PyObjC 10.3 initially removed the ability to call `__init__` on Objective-C classes when a Python class (or its superclass) defines `__new__`. While 10.3.1 partially reintroduced this for user-implemented `__new__`, it remains a nuanced interaction where standard Python object initialization patterns might clash with PyObjC's object lifecycle.
  Fix: When subclassing Objective-C classes in Python and overriding `__new__`, be cautious about how `__init__` is used. Prefer `alloc().init*()` patterns directly, or ensure your `__new__` and `__init__` adhere to PyObjC's expectations for Objective-C object construction.
• gotcha PyObjC 11.0 introduced *experimental* support for free-threading (PEP 703) in Python 3.13. While this is an exciting development, experimental features may have stability issues or unexpected behavior. Note that earlier versions (e.g., 10.3) explicitly stated lack of support for Python 3.13's free threading.
  Fix: If working with Python 3.13 and PyObjC in a free-threaded environment, be prepared for potential stability issues. It is recommended to thoroughly test your application and refer to PyObjC's latest documentation regarding free-threading compatibility.

Install

• pip install pyobjc-framework-medialibrary Install specific framework
• pip install pyobjc Install meta-package (includes all frameworks)

Imports

• MLMediaLibrary

  from MediaLibrary import MLMediaLibrary

  PyObjC maps macOS frameworks to Python packages with the same name. Classes within the framework are available directly from the imported package.

Quickstart

This quickstart demonstrates how to import and instantiate the `MLMediaLibrary` class to access macOS media sources. Due to restrictions of the underlying macOS framework, this code may encounter runtime errors (e.g., 'XPC connection interrupted') if not executed within a properly signed macOS application bundle or without appropriate entitlements.

import MediaLibrary

# Create an instance of MLMediaLibrary
# WARNING: MLMediaLibrary often requires running within a macOS application bundle
# or with specific entitlements to avoid 'XPC connection interrupted' errors
# in command-line contexts. This example may not function fully outside an app.
try:
    media_library = MediaLibrary.MLMediaLibrary.alloc().initWithOptions_(None)
    if media_library:
        print(f"Successfully instantiated MLMediaLibrary: {media_library}")
        # Attempt to get media sources - this might fail if not in an app context
        media_sources = media_library.mediaSources()
        if media_sources:
            print(f"Found {len(media_sources)} media sources.")
            for source in media_sources:
                # Accessing properties like mediaSourceIdentifier() might require an active app context.
                try:
                    identifier = source.mediaSourceIdentifier()
                    print(f"- Source Identifier: {identifier}")
                except Exception as prop_e:
                    print(f"- Could not get source identifier for a media source: {prop_e}")
        else:
            print("No media sources found or could not access them.")
    else:
        print("Failed to instantiate MLMediaLibrary (returned None).")
except Exception as e:
    print(f"An error occurred during MLMediaLibrary instantiation or access: {e}")
    print("This often indicates issues with entitlements or running outside an app bundle.")