PyObjC Framework MediaAccessibility

Warnings

• breaking 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.
  Fix: Upgrade to Python 3.10 or later. For Python 3.9, the last supported version is PyObjC 11.1.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Only use `pyobjc-framework-mediaaccessibility` in macOS environments. For cross-platform applications, alternative accessibility libraries must be used.
• gotcha 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.
  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).

Install

• pip install pyobjc-framework-mediaaccessibility Install stable version

Imports

• MediaAccessibility

  import MediaAccessibility

  PyObjC frameworks are typically imported as modules matching the framework name.

Quickstart

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.

import MediaAccessibility

# Get the currently selected caption language for the user domain
selected_language = MediaAccessibility.MACaptionAppearanceCopySelectedLanguage(
    MediaAccessibility.kMACaptionAppearanceDomainUser
)

if selected_language:
    print(f"Selected caption language (user domain): {selected_language}")
else:
    print("No selected caption language found for the user domain.")

# Note: MACaptionAppearanceCopySelectedLanguage returns a CFStringRef, which PyObjC
# automatically bridges to a Python string. Memory management (release) is typically
# handled by PyObjC for bridged objects.