{"id":6132,"library":"pyobjc-framework-mediaaccessibility","title":"PyObjC Framework MediaAccessibility","description":"pyobjc-framework-mediaaccessibility provides Python bindings for Apple's MediaAccessibility framework on macOS. It allows Python developers to interact with system-wide media accessibility settings, such as closed captions and audio descriptions. The library is part of the larger PyObjC project, which regularly releases updates, typically aligning with new macOS SDKs and Python versions. The current version is 12.1.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macOS","Objective-C","Cocoa","Accessibility","UI","Apple Frameworks"],"install":[{"cmd":"pip install pyobjc-framework-mediaaccessibility","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"The core bridge between Python and Objective-C, required by all PyObjC framework wrappers.","package":"pyobjc-core","optional":false}],"imports":[{"note":"PyObjC frameworks are typically imported as modules matching the framework name.","symbol":"MediaAccessibility","correct":"import MediaAccessibility"}],"quickstart":{"code":"import MediaAccessibility\n\n# Get the currently selected caption language for the user domain\nselected_language = MediaAccessibility.MACaptionAppearanceCopySelectedLanguage(\n    MediaAccessibility.kMACaptionAppearanceDomainUser\n)\n\nif selected_language:\n    print(f\"Selected caption language (user domain): {selected_language}\")\nelse:\n    print(\"No selected caption language found for the user domain.\")\n\n# Note: MACaptionAppearanceCopySelectedLanguage returns a CFStringRef, which PyObjC\n# automatically bridges to a Python string. Memory management (release) is typically\n# handled by PyObjC for bridged objects.","lang":"python","description":"This quickstart demonstrates how to import the MediaAccessibility framework and retrieve the currently selected caption language for the user domain using a standard C function binding."},"warnings":[{"fix":"Upgrade to Python 3.10 or later. For Python 3.9, the last supported version is PyObjC 11.1.","message":"PyObjC 12.0 and later (including 12.1) officially dropped support for Python 3.9. Attempting to install or use pyobjc-framework-mediaaccessibility==12.x on Python 3.9 will result in errors.","severity":"breaking","affected_versions":">=12.0"},{"fix":"Review Python subclasses of Objective-C classes, particularly how `__init__` and `__new__` are implemented. Consider refactoring to use Objective-C designated initializers or explicitly managing `__new__` and `__init__` as per PyObjC's documentation.","message":"PyObjC 10.3 introduced changes to `__init__` and `__new__` interaction, where `__init__` could not be used if PyObjC provided `__new__`. Version 10.3.1 partially reverted this, reintroducing `__init__` support if the user provides their own `__new__` implementation. If you rely on custom `__init__` methods in Python subclasses of Objective-C classes, this might break your code, especially if upgrading from pre-10.3 versions.","severity":"breaking","affected_versions":"10.3, 10.3.1"},{"fix":"When using PyObjC in a free-threaded Python environment, always assume Apple's frameworks are not thread-safe. Implement explicit locking (e.g., `threading.Lock`) around any calls to Objective-C APIs or access to Objective-C objects that might be shared or modified across multiple threads.","message":"PyObjC supports experimental free-threading (PEP 703) introduced in Python 3.13. While PyObjC itself strives for thread-safety, Apple's underlying Objective-C frameworks (including MediaAccessibility) are not guaranteed to be thread-safe. Concurrent access to Objective-C objects or APIs from multiple Python threads without proper locking can lead to crashes or undefined behavior.","severity":"gotcha","affected_versions":">=11.0 (with Python >=3.13)"},{"fix":"Ensure `pyobjc-core` is installed alongside any `pyobjc-framework-*` package, typically by installing `pyobjc` which pulls in `pyobjc-core` and common frameworks as dependencies, or by explicitly installing `pyobjc-core` first.","message":"All `pyobjc-framework-*` packages, including `pyobjc-framework-mediaaccessibility`, require `pyobjc-core` to function. Installing only a specific framework package without `pyobjc` (the meta-package) or `pyobjc-core` explicitly can lead to `ImportError` or other runtime failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Only use `pyobjc-framework-mediaaccessibility` in macOS environments. For cross-platform applications, alternative accessibility libraries must be used.","message":"PyObjC is a macOS-specific library and will not function on other operating systems like Linux or Windows. Its entire purpose is to bridge Python with Apple's Objective-C frameworks.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to Apple Developer documentation for the MediaAccessibility framework to understand the API details. PyObjC generally translates Objective-C naming conventions directly to Python (e.g., `MACaptionAppearanceCopySelectedLanguage` from C becomes `MediaAccessibility.MACaptionAppearanceCopySelectedLanguage` in Python).","message":"PyObjC framework wrappers generally do not include extensive Python-specific docstrings for the wrapped Objective-C APIs. Users are expected to consult Apple's official MediaAccessibility framework documentation for details on classes, methods, constants, and function usage.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}