{"id":6134,"library":"pyobjc-framework-medialibrary","title":"PyObjC MediaLibrary Framework","description":"pyobjc-framework-medialibrary provides Python wrappers for the macOS MediaLibrary framework, which allows access to media content managed by applications like Photos, Music, and TV. It is part of the larger PyObjC project, a bridge that enables Python scripts to interact with Objective-C class libraries, most notably Apple's Cocoa frameworks. The current version is 12.1, and the project maintains an active release cadence, frequently updating bindings for new macOS SDKs.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","framework","objective-c","cocoa","medialibrary","apple"],"install":[{"cmd":"pip install pyobjc-framework-medialibrary","lang":"bash","label":"Install specific framework"},{"cmd":"pip install pyobjc","lang":"bash","label":"Install meta-package (includes all frameworks)"}],"dependencies":[{"reason":"This package is a wrapper for a macOS framework and relies on the core PyObjC bridge functionality.","package":"pyobjc-core"}],"imports":[{"note":"PyObjC maps macOS frameworks to Python packages with the same name. Classes within the framework are available directly from the imported package.","symbol":"MLMediaLibrary","correct":"from MediaLibrary import MLMediaLibrary"}],"quickstart":{"code":"import MediaLibrary\n\n# Create an instance of MLMediaLibrary\n# WARNING: MLMediaLibrary often requires running within a macOS application bundle\n# or with specific entitlements to avoid 'XPC connection interrupted' errors\n# in command-line contexts. This example may not function fully outside an app.\ntry:\n    media_library = MediaLibrary.MLMediaLibrary.alloc().initWithOptions_(None)\n    if media_library:\n        print(f\"Successfully instantiated MLMediaLibrary: {media_library}\")\n        # Attempt to get media sources - this might fail if not in an app context\n        media_sources = media_library.mediaSources()\n        if media_sources:\n            print(f\"Found {len(media_sources)} media sources.\")\n            for source in media_sources:\n                # Accessing properties like mediaSourceIdentifier() might require an active app context.\n                try:\n                    identifier = source.mediaSourceIdentifier()\n                    print(f\"- Source Identifier: {identifier}\")\n                except Exception as prop_e:\n                    print(f\"- Could not get source identifier for a media source: {prop_e}\")\n        else:\n            print(\"No media sources found or could not access them.\")\n    else:\n        print(\"Failed to instantiate MLMediaLibrary (returned None).\")\nexcept Exception as e:\n    print(f\"An error occurred during MLMediaLibrary instantiation or access: {e}\")\n    print(\"This often indicates issues with entitlements or running outside an app bundle.\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your Python environment is 3.10 or newer. Consider using Python 3.11 or later for the best compatibility and features.","message":"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.","severity":"breaking","affected_versions":">=12.0 (Python 3.9), >=11.0 (Python 3.8)"},{"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.","message":"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.","severity":"breaking","affected_versions":">=11.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=10.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=11.0 with Python 3.13+"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}