PyObjC AVFoundation Framework

12.1 · active · verified Mon Apr 13

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.

Warnings

breaking 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.
Fix: Upgrade your Python interpreter to a supported version (e.g., Python 3.10+ for PyObjC 12.x).
breaking 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.
Fix: Change imports from `from AVFoundation import ...` to `from AVFAudio import ...` for `AVFAudio` specific classes (e.g., `AVAudioEngine`, `AVAudioPlayerNode`).
breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install pyobjc-framework-avfoundation Install pyobjc-framework-avfoundation

Imports

AVCaptureSession
```
from AVFoundation import AVCaptureSession
```
Primary class for managing audio/video capture.
AVCaptureDevice
```
from AVFoundation import AVCaptureDevice
```
For enumerating and configuring capture devices (cameras, microphones).
AVAudioEngine
```
from AVFAudio import AVAudioEngine
```
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.
NSLog
```
from Foundation import NSLog
```
Common utility for logging to system console, part of the core Foundation framework.

Quickstart

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.

from AVFoundation import AVCaptureDevice
from Foundation import NSLog

def list_capture_devices():
    NSLog("\n--- Listing Available Capture Devices ---")
    devices = AVCaptureDevice.devices()
    if not devices:
        NSLog("No capture devices found.")
        return

    for i, device in enumerate(devices):
        name = device.localizedName()
        unique_id = device.uniqueID()
        has_video = device.hasMediaType('vide')
        has_audio = device.hasMediaType('soun')
        
        NSLog(f"  {i+1}. Name: {name}, UniqueID: {unique_id}")
        if has_video: NSLog("     - Supports video capture")
        if has_audio: NSLog("     - Supports audio capture")
    NSLog("-----------------------------------------")

if __name__ == "__main__":
    # Note: For full GUI apps, you would typically run an NSApplication event loop.
    # For simple scripts, direct calls often work, but some operations might require
    # a run loop for asynchronous callbacks or permissions.
    list_capture_devices()

view raw JSON →