PyObjC iTunesLibrary Framework

Warnings

• breaking PyObjC has periodically dropped support for older Python versions to align with Python's end-of-life schedule and leverage newer Python features.
  Fix: Ensure your Python environment meets the minimum requirement. PyObjC 12.x requires Python 3.10+, PyObjC 11.x requires Python 3.9+.
• gotcha Accessing the iTunes/Music Library.framework requires 'Full Disk Access' permission for the Python application (or its parent process like Terminal/IDE) in macOS System Settings.
  Fix: Grant 'Full Disk Access' to your terminal, IDE, or the Python executable running the script in System Settings > Privacy & Security > Full Disk Access.
• gotcha PyObjC 10.3 introduced breaking changes regarding the interaction between `__init__` and PyObjC's `__new__` for Objective-C wrapped classes. While partially reverted in 10.3.1 for user-defined `__new__`, direct `__init__` usage with PyObjC-provided `__new__` might still behave differently.
  Fix: When subclassing Objective-C classes, generally avoid overriding `__init__` if `__new__` is not also overridden. If you must use `__init__`, ensure it's compatible with the new object creation flow or explicitly override `__new__` as well.
• gotcha PyObjC 11.1 changed how it models 'init' family methods (e.g., `initWithObjects_`) to align with Clang's Automatic Reference Counting (ARC) behavior, specifically regarding reference stealing for `self` and returning a new reference. This could affect memory management or object lifecycle in advanced scenarios.
  Fix: Review custom Python wrappers around Objective-C `init` methods, especially those dealing with explicit retain/release cycles (though less common with modern ARC). Ensure your code correctly handles object ownership if directly interacting with such methods.

Install

• pip install pyobjc-framework-ituneslibrary Install latest version

Imports

• ITLibrary

  from iTunesLibrary import ITLibrary

  The primary class for accessing the iTunes/Music library.

Quickstart

This quickstart demonstrates how to load the user's iTunes/Music library and print some basic information about it. It uses the `ITLibrary` class to access media items and playlists. Note the requirement for macOS 'Full Disk Access' to prevent permission errors.

import os
from iTunesLibrary import ITLibrary

def get_itunes_library_info():
    """
    Retrieves and prints basic information from the user's Music library.
    Requires 'Full Disk Access' for the Python application in macOS System Settings.
    """
    try:
        # API Version 1 is generally current for basic access
        library = ITLibrary.libraryWithAPIVersion_error_(1, None)
        if library:
            print(f"Library Name: {library.applicationDisplayName()}")
            print(f"Total Tracks: {len(library.allMediaItems())}")
            print(f"Number of Playlists: {len(library.allPlaylists())}")

            # Example: Iterate through first 3 tracks
            print("\nFirst 3 Tracks:")
            for i, item in enumerate(library.allMediaItems()):
                if i >= 3:
                    break
                title = item.title()
                artist = item.artist().name() if item.artist() else "Unknown Artist"
                album = item.album().title() if item.album() else "Unknown Album"
                print(f"- Title: {title}, Artist: {artist}, Album: {album}")
                
                # Get file path if available
                if item.location():
                    file_path = os.fspath(item.location()) # Requires PyObjC 10.1+
                    # print(f"  Path: {file_path}") # Uncomment to see paths
        else:
            print("Failed to load iTunes Library.")

    except Exception as e:
        print(f"An error occurred: {e}")
        print("\nNote: Accessing the iTunes/Music Library typically requires 'Full Disk Access' for your Python application (or its parent process like Terminal/IDE) in macOS System Settings > Privacy & Security.")

if __name__ == "__main__":
    get_itunes_library_info()