PyObjC ShazamKit Framework

12.1 · active · verified Tue Apr 14

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.

Warnings

breaking 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`).
Fix: Upgrade your Python environment to version 3.10 or newer, or use an older PyObjC version that supports your Python installation.
gotcha 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.
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.
breaking 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.
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.
breaking 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.
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.
gotcha 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.
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.

Install

pip install pyobjc-framework-shazamkit Install pyobjc-framework-shazamkit

Imports

SHSession
```
from ShazamKit import SHSession
```
While 'import ShazamKit' works, direct import of classes like SHSession is standard practice and more explicit.
SHMediaItem
```
from ShazamKit import SHMediaItem
```
SHSignature
```
from ShazamKit import SHSignature
```

Quickstart

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.

import platform
from ShazamKit import SHMediaItem, SHErrorDomain, SHSession

if platform.system() != "Darwin":
    print("ShazamKit is a macOS-only framework. This code will only execute PyObjC specific parts on macOS.")
else:
    try:
        # Verify core PyObjC bridge and ShazamKit framework are loadable
        _ = SHMediaItem  # Accessing a class to ensure it's bound
        _ = SHSession
        error_domain = SHErrorDomain # Accessing a constant

        print(f"Successfully imported ShazamKit framework on macOS.")
        print(f"SHMediaItem class type: {type(SHMediaItem)}")
        print(f"SHErrorDomain constant: {error_domain}")

        # To use ShazamKit effectively, you would typically:
        # 1. Request microphone permissions.
        # 2. Create an SHSession with a custom SHSessionDelegate (inheriting from objc.retains('SHSessionDelegate')).
        # 3. Capture audio and create an SHSignature.
        # 4. Call session.matchSignature(signature).
        # This quickstart merely confirms the library's basic availability.

    except ImportError:
        print("Error: ShazamKit framework not found. Ensure 'pyobjc-framework-shazamkit' is installed and you are on macOS.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →