{"id":6087,"library":"pyobjc-framework-corehaptics","title":"PyObjC CoreHaptics Framework","description":"This library provides Python bindings for Apple's CoreHaptics framework on macOS, allowing developers to integrate sophisticated haptic feedback into their applications. As part of the larger PyObjC bridge, it enables direct interaction with Objective-C APIs from Python. The current version is 12.1, and releases generally follow macOS SDK updates and Python version support changes.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","framework-bindings","haptics","objective-c","pyobjc"],"install":[{"cmd":"pip install pyobjc-framework-corehaptics","lang":"bash","label":"Install pyobjc-framework-corehaptics"}],"dependencies":[{"reason":"Core bridge for Objective-C runtime interaction, required by all PyObjC framework bindings.","package":"pyobjc-core"}],"imports":[{"note":"Main class for managing haptic feedback.","symbol":"CHHapticEngine","correct":"from CoreHaptics import CHHapticEngine"},{"note":"Represents a single haptic event within a pattern.","symbol":"CHHapticEvent","correct":"from CoreHaptics import CHHapticEvent"},{"note":"Defines a sequence of haptic events and parameters.","symbol":"CHHapticPattern","correct":"from CoreHaptics import CHHapticPattern"},{"note":"Constants for haptic event parameters (e.g., intensity, sharpness).","symbol":"CHHapticEventParameterID","correct":"from CoreHaptics import CHHapticEventParameterID"},{"note":"Required for creating Objective-C array objects.","symbol":"NSArray","correct":"from Foundation import NSArray"},{"note":"Useful for pausing execution in script contexts.","symbol":"NSThread","correct":"from Foundation import NSThread"},{"note":"The core PyObjC module, providing access to Objective-C runtime utilities.","symbol":"objc","correct":"import objc"}],"quickstart":{"code":"import objc\nfrom CoreHaptics import (\n    CHHapticEngine, CHHapticPattern, CHHapticEvent,\n    CHHapticEventParameter, CHHapticEventParameterID, CHHapticEventType\n)\nfrom Foundation import NSArray, NSThread\n\ndef play_haptic_feedback():\n    \"\"\"\n    Initializes a CHHapticEngine and plays a simple haptic impact.\n    Requires macOS and haptic feedback enabled.\n    \"\"\"\n    print(\"Attempting to play haptic feedback...\")\n\n    # Create an error holder (PyObjC will populate if an error occurs)\n    error = objc.nil\n\n    # 1. Initialize the haptic engine\n    engine = CHHapticEngine.alloc().initAndReturnError_(objc.ptr(error))\n    if engine is None:\n        print(f\"Error initializing CHHapticEngine: {error[0] if error else 'Unknown error'}\")\n        return\n\n    # 2. Set an error handler for the engine\n    engine.setErrorHandler_(lambda err: print(f\"CHHapticEngine encountered an error: {err}\"))\n\n    # 3. Start the engine\n    success, error = engine.startAndReturnError_(objc.ptr(error))\n    if not success:\n        print(f\"Error starting CHHapticEngine: {error[0] if error else 'Unknown error'}\")\n        return\n    print(\"CHHapticEngine started.\")\n\n    # 4. Create haptic event parameters\n    intensity_param = CHHapticEventParameter.alloc().initWithParameterID_value_(\n        CHHapticEventParameterID.CHHapticEventParameterIDHapticIntensity, 0.8\n    )\n    sharpness_param = CHHapticEventParameter.alloc().initWithParameterID_value_(\n        CHHapticEventParameterID.CHHapticEventParameterIDHapticSharpness, 0.6\n    )\n\n    # 5. Create a haptic event (a transient impact)\n    event = CHHapticEvent.alloc().initWithEventType_parameters_relativeTime_duration_(\n        CHHapticEventType.CHHapticEventTypeHapticTransient,\n        NSArray.arrayWithArray_([intensity_param, sharpness_param]),\n        0.0,\n        0.1\n    )\n\n    # 6. Create a haptic pattern from the event\n    pattern = CHHapticPattern.alloc().initWithEvents_parameters_error_(\n        NSArray.arrayWithArray_([event]),\n        objc.nil,\n        objc.ptr(error)\n    )\n    if pattern is None:\n        print(f\"Error creating CHHapticPattern: {error[0] if error else 'Unknown error'}\")\n        engine.stopWithCompletionHandler_(objc.nil)\n        return\n\n    # 7. Create a player for the pattern\n    player, error = engine.createPlayerWithPattern_error_(pattern, objc.ptr(error))\n    if player is None:\n        print(f\"Error creating CHHapticPatternPlayer: {error[0] if error else 'Unknown error'}\")\n        engine.stopWithCompletionHandler_(objc.nil)\n        return\n\n    # 8. Start the player\n    success, error = player.startAtTime_error_(0, objc.ptr(error))\n    if not success:\n        print(f\"Error starting CHHapticPatternPlayer: {error[0] if error else 'Unknown error'}\")\n        engine.stopWithCompletionHandler_(objc.nil)\n        return\n    print(\"Haptic pattern started playing.\")\n\n    # 9. Keep the script alive long enough for the haptic to play\n    NSThread.sleepForTimeInterval_(1.5)\n\n    # 10. Stop the engine gracefully\n    success, error = engine.stopAndReturnError_(objc.ptr(error))\n    if not success:\n        print(f\"Error stopping CHHapticEngine: {error[0] if error else 'Unknown error'}\")\n    print(\"CHHapticEngine stopped.\")\n\nif __name__ == \"__main__\":\n    play_haptic_feedback()\n","lang":"python","description":"This quickstart demonstrates how to initialize the `CHHapticEngine`, define a simple haptic impact using `CHHapticEvent` and `CHHapticEventParameter`, create a `CHHapticPattern`, and play it. This code will only run on macOS systems with haptic feedback capabilities. Ensure your system's haptic settings are enabled."},"warnings":[{"fix":"Upgrade your Python environment to a version supported by the latest PyObjC, typically Python 3.10 or later for PyObjC 12.x.","message":"PyObjC versions 11.0 and 12.0 dropped support for older Python versions. Specifically, PyObjC 11.0 dropped Python 3.8, and PyObjC 12.0 dropped Python 3.9. Attempting to install or run PyObjC 11.x on Python 3.8 or PyObjC 12.x on Python 3.9 will result in compatibility errors.","severity":"breaking","affected_versions":">=11.0 (for Python 3.8), >=12.0 (for Python 3.9)"},{"fix":"Review Python-implemented `init` methods for custom Objective-C classes. Manual `retain`/`release` logic that compensated for older PyObjC behavior may now be incorrect and could lead to memory leaks or crashes. Generally, this change simplifies correct ARC behavior, but existing code might need adaptation.","message":"As of PyObjC 11.1, the core bridge's Automatic Reference Counting (ARC) behavior for 'init' family methods (e.g., methods starting with `init`) has been aligned with clang's documentation. Methods in the 'init' family now correctly steal a reference to `self` and return a new one. This is a fundamental change in object lifecycle management for Objective-C classes implemented in Python.","severity":"breaking","affected_versions":">=11.1"},{"fix":"When defining Objective-C classes in Python using PyObjC, if you are not explicitly defining `__new__`, avoid implementing `__init__` in the Python class. Instead, rely on `initWith...` methods directly for Objective-C object initialization.","message":"PyObjC 10.3 initially removed support for calling `__init__` on classes where PyObjC implicitly provides `__new__`. While PyObjC 10.3.1 restored `__init__` functionality if *your code* explicitly defines `__new__` in the Python class, `__init__` still cannot be used for classes solely relying on PyObjC's default `__new__` method for Objective-C object creation.","severity":"gotcha","affected_versions":">=10.3"},{"fix":"Avoid using PyObjC with free-threading enabled Python 3.13 builds until full, stable support is officially announced to prevent potential crashes or undefined behavior.","message":"PyObjC versions 10.3 and 11.0 introduced experimental support for Python 3.13 but explicitly state that they do not fully support the experimental free-threading (PEP 703) features. Significant internal changes were made, but stability with free-threading is not guaranteed and could lead to crashes or undefined behavior.","severity":"gotcha","affected_versions":">=10.3 (when using Python 3.13 with free-threading)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}