{"id":6176,"library":"pyobjc-framework-shazamkit","title":"PyObjC ShazamKit Framework","description":"PyObjC-framework-shazamkit provides Python bindings for Apple's ShazamKit framework on macOS, allowing Python applications to identify music and audio using Shazam's technology. It's part of the larger PyObjC project, which offers comprehensive access to macOS frameworks. The current version is 12.1, with releases typically tied to 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","shazam","audio","pyobjc","bindings"],"install":[{"cmd":"pip install pyobjc-framework-shazamkit","lang":"bash","label":"Install pyobjc-framework-shazamkit"}],"dependencies":[{"reason":"All pyobjc-framework-* packages depend on pyobjc-core for the underlying bridge functionality.","package":"pyobjc-core","optional":false}],"imports":[{"note":"While 'import ShazamKit' works, direct import of classes like SHSession is standard practice and more explicit.","wrong":"import ShazamKit; session = ShazamKit.SHSession()","symbol":"SHSession","correct":"from ShazamKit import SHSession"},{"symbol":"SHMediaItem","correct":"from ShazamKit import SHMediaItem"},{"symbol":"SHSignature","correct":"from ShazamKit import SHSignature"}],"quickstart":{"code":"import platform\nfrom ShazamKit import SHMediaItem, SHErrorDomain, SHSession\n\nif platform.system() != \"Darwin\":\n    print(\"ShazamKit is a macOS-only framework. This code will only execute PyObjC specific parts on macOS.\")\nelse:\n    try:\n        # Verify core PyObjC bridge and ShazamKit framework are loadable\n        _ = SHMediaItem  # Accessing a class to ensure it's bound\n        _ = SHSession\n        error_domain = SHErrorDomain # Accessing a constant\n\n        print(f\"Successfully imported ShazamKit framework on macOS.\")\n        print(f\"SHMediaItem class type: {type(SHMediaItem)}\")\n        print(f\"SHErrorDomain constant: {error_domain}\")\n\n        # To use ShazamKit effectively, you would typically:\n        # 1. Request microphone permissions.\n        # 2. Create an SHSession with a custom SHSessionDelegate (inheriting from objc.retains('SHSessionDelegate')).\n        # 3. Capture audio and create an SHSignature.\n        # 4. Call session.matchSignature(signature).\n        # This quickstart merely confirms the library's basic availability.\n\n    except ImportError:\n        print(\"Error: ShazamKit framework not found. Ensure 'pyobjc-framework-shazamkit' is installed and you are on macOS.\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart verifies that the PyObjC ShazamKit binding can be imported and its core components (classes, constants) are accessible. Note that actual ShazamKit functionality (audio recording, matching) requires microphone permissions, an `SHSessionDelegate` implementation, and often an `NSRunLoop` for asynchronous operations, which are beyond this basic setup."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer, or use an older PyObjC version that supports your Python installation.","message":"PyObjC has consistently dropped support for older Python versions. Version 12.0 dropped Python 3.9, and 11.0 dropped Python 3.8. Ensure your Python version meets the `requires_python` spec (currently `>=3.10`).","severity":"breaking","affected_versions":"11.0, 12.0"},{"fix":"Avoid relying on PEP 703 free-threading with PyObjC, or test thoroughly for compatibility. Use traditional Python threading models (GIL-bound) for critical sections involving PyObjC.","message":"PyObjC does not fully support experimental free-threading (PEP 703) in Python 3.13, despite binary wheels being available. This can lead to unexpected behavior or performance issues if free-threading is enabled and used with PyObjC components.","severity":"gotcha","affected_versions":"10.3 and later (Python 3.13+)"},{"fix":"Review custom Python `__init__` and `__new__` implementations on subclasses of Objective-C classes. If `__new__` is implemented by the user, `__init__` is now callable (as of 10.3.1). If relying on PyObjC's `__new__`, `__init__` is generally not callable.","message":"Behavioral changes to `__init__` and `__new__` for Python subclasses of Objective-C classes were introduced in PyObjC v10.3 and partially reverted in v10.3.1. Custom instantiation logic might break.","severity":"breaking","affected_versions":"10.3, 10.3.1"},{"fix":"Developers working with complex Objective-C object lifecycle management or manual reference counting scenarios in Python should review their code for potential reference count imbalances or memory issues, especially around object initialization.","message":"Automatic Reference Counting (ARC) behavior for initializer methods (`init`-family methods) was aligned with `clang` documentation in v11.1. This means PyObjC now correctly models that `init` methods steal a reference to `self` and return a new one.","severity":"breaking","affected_versions":"11.1 and later"},{"fix":"Ensure your development and deployment environment is macOS. For `ShazamKit` specifically, this also often implies needing microphone access permissions and managing an `NSRunLoop` for asynchronous callback handling.","message":"PyObjC framework packages like `pyobjc-framework-shazamkit` are macOS-specific and require a compatible macOS version and Xcode SDK. They will not work on other operating systems.","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","problems":[]}