hendriks73/jitlibrary

Java API for the native Apple iTunes Library Framework for Music.app and iTunes (macOS)

jITLibrary

jITLibrary is a thin wrapper around the Apple iTunes Library Framework, which - despite its name - can also be used to access Music.app data. Note that the API is read-only, just like Apple's framework. For write access, see Obstmusic or Obstunes.

Important

You must code sign your app to retrieve information with this framework, and iTunes library access is read-only. This framework is available to users with iTunes 11 or later (also Music.app).

Installation

jITLibrary is released via Maven. You can install it via the following dependency:

<dependencies>
    <dependency>
        <groupId>com.tagtraum</groupId>
        <artifactId>jitlibrary</artifactId>
    </dependency>
</dependencies>

Java Module

jITLibrary is shipped as a Java module (see JPMS) with the name tagtraum.jitlibrary.

Usage

Once you have obtained an ITLibrary instance you may access its ITMediaItems and ITPlaylists as you like.

Example:

import com.tagtraum.jitlibrary.*;

public class ListAllMediaItems {

    public static void main(final String args) throws Exception {
        // get library (blocking call)
        final ITLibrary itLibrary = ITLibrary.getInstance(true);
        // get the natively backed collection
        final ITLibMediaItems allMediaItems = itLibrary.getAllMediaItems();
        
        // print size if library
        final int length = allMediaItems.size();
        System.out.println("Library size: " + length);

        // iterate over the library and print names and artists
        for (int i=0; i<length; i++) {
            final ITLibMediaItem item = allMediaItems.getMediaItem(i);
            System.out.println("Item named " + item.getName() + " by " + item.getArtist());
        }
    }
}

Note that you should not call ITLibrary.getInstance(..) from the Event Dispatch Thread (EDT, i.e. the AWT/Swing thread). Also note that this library is not necessarily thread-safe.

Logging

jITLibrary uses java.util.logging.

Known Shortcomings

• Apple's code signing requirement sucks
• thread safety may be an issue
• reloading data after changes my not be quick

API

You can find the complete API here.

Additional Resources

• iTunes Library Framework
• Apple's Code Signing Guide
• Obstmusic
• Obstunes