{"id":5405,"library":"pyobjc-framework-avfoundation","title":"PyObjC AVFoundation Framework","description":"PyObjC-framework-AVFoundation provides Python wrappers for Apple's AVFoundation framework on macOS. It allows Python applications to interact with audio and video capture, playback, and processing capabilities. The library is actively maintained, generally seeing releases multiple times a year, often aligning with new macOS SDK updates and Python version changes. 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","frameworks","audio","video","avfoundation"],"install":[{"cmd":"pip install pyobjc-framework-avfoundation","lang":"bash","label":"Install pyobjc-framework-avfoundation"}],"dependencies":[{"reason":"Provides the core Objective-C bridge functionality that all PyObjC framework wrappers depend on.","package":"pyobjc-core"}],"imports":[{"note":"Primary class for managing audio/video capture.","symbol":"AVCaptureSession","correct":"from AVFoundation import AVCaptureSession"},{"note":"For enumerating and configuring capture devices (cameras, microphones).","symbol":"AVCaptureDevice","correct":"from AVFoundation import AVCaptureDevice"},{"note":"AVAudioEngine and related audio classes moved from AVFoundation to the top-level AVFAudio package in PyObjC 12.0. Use 'from AVFAudio import ...' for versions 12.0 and later.","wrong":"from AVFoundation import AVAudioEngine","symbol":"AVAudioEngine","correct":"from AVFAudio import AVAudioEngine"},{"note":"Common utility for logging to system console, part of the core Foundation framework.","symbol":"NSLog","correct":"from Foundation import NSLog"}],"quickstart":{"code":"from AVFoundation import AVCaptureDevice\nfrom Foundation import NSLog\n\ndef list_capture_devices():\n    NSLog(\"\\n--- Listing Available Capture Devices ---\")\n    devices = AVCaptureDevice.devices()\n    if not devices:\n        NSLog(\"No capture devices found.\")\n        return\n\n    for i, device in enumerate(devices):\n        name = device.localizedName()\n        unique_id = device.uniqueID()\n        has_video = device.hasMediaType('vide')\n        has_audio = device.hasMediaType('soun')\n        \n        NSLog(f\"  {i+1}. Name: {name}, UniqueID: {unique_id}\")\n        if has_video: NSLog(\"     - Supports video capture\")\n        if has_audio: NSLog(\"     - Supports audio capture\")\n    NSLog(\"-----------------------------------------\")\n\nif __name__ == \"__main__\":\n    # Note: For full GUI apps, you would typically run an NSApplication event loop.\n    # For simple scripts, direct calls often work, but some operations might require\n    # a run loop for asynchronous callbacks or permissions.\n    list_capture_devices()\n","lang":"python","description":"This quickstart demonstrates how to use AVFoundation to enumerate available audio and video capture devices on macOS, printing their names and capabilities to the console. It uses `AVCaptureDevice` from `AVFoundation` and `NSLog` from `Foundation` for output."},"warnings":[{"fix":"Upgrade your Python interpreter to a supported version (e.g., Python 3.10+ for PyObjC 12.x).","message":"PyObjC frequently drops support for older Python versions. Version 12.0 dropped support for Python 3.9, and 11.0 dropped Python 3.8. Ensure your Python environment meets the 'requires_python' specification for the PyObjC version you are using.","severity":"breaking","affected_versions":"11.0, 12.0"},{"fix":"Change imports from `from AVFoundation import ...` to `from AVFAudio import ...` for `AVFAudio` specific classes (e.g., `AVAudioEngine`, `AVAudioPlayerNode`).","message":"The `AVFAudio` framework bindings were moved from being merged into `AVFoundation` to a separate top-level package `AVFAudio`. Code importing classes like `AVAudioEngine` from `AVFoundation` will break.","severity":"breaking","affected_versions":"12.0 and later"},{"fix":"Review custom Python subclasses of Objective-C classes, especially those overriding `init` methods, to ensure they handle object references correctly under the new ARC model. Most standard usage should be unaffected, but complex reference counting scenarios might require adjustments.","message":"PyObjC 11.1 introduced changes to align the core bridge's behavior with `clang`'s documentation for Automatic Reference Counting (ARC) regarding initializer methods. Methods in the 'init' family now correctly steal a reference to self and return a new one, which might affect custom object initialization patterns.","severity":"breaking","affected_versions":"11.1 and later"},{"fix":"If implementing custom `__new__` for PyObjC classes, ensure compatibility by testing thoroughly. PyObjC 10.3.1 and later restored expected behavior for `__init__` when `__new__` is user-defined, but it's a known area of complexity.","message":"There have been changes and subsequent fixes regarding the interaction of Python's `__init__` and `__new__` methods in PyObjC classes. Specifically, calling `__init__` when a user-defined `__new__` is present was temporarily broken in 10.3 and fixed in 10.3.1.","severity":"gotcha","affected_versions":"10.3"},{"fix":"If working with Python 3.13 and free-threading, consult the latest PyObjC release notes for stability updates. For critical applications, consider using Python versions without free-threading (e.g., 3.12) until free-threading support is fully mature in PyObjC.","message":"PyObjC introduced experimental support for free-threading (PEP 703) with Python 3.13 in version 11.0, though initial releases (e.g., PyObjC 10.3) explicitly stated it was not supported. While work is ongoing, reliance on free-threading with PyObjC might lead to instability or unexpected behavior in early Python 3.13 versions.","severity":"gotcha","affected_versions":"11.0 and earlier Python 3.13 support"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}