MusicLib

Python bindings for Apple's iTunes Library (ITlib) API, enabling programmatic access to iTunes/Music library data on macOS with powerful export and organization tools.

Overview

MusicLib provides a comprehensive Python interface to access iTunes/Music library information with advanced data export and music organization capabilities:

Core Library Access

• Media items (songs, tracks) with comprehensive metadata (title, artist, album, duration, bitrate, ratings, etc.)
• Playlists and their contents
• Library folder locations and file paths
• Search functionality by title and artist
• Performance benchmarking tools

Data Export & Analysis

• CSV Export: Export library data with extensive filtering and search options
• Excel Export: Rich formatted exports with multiple worksheet support
• JSON/Parquet: Support for modern data formats
• Advanced Filtering: Filter by genre, year, bitrate, rating, date added, and more
• Search Capabilities: Full-text search across titles, artists, and albums
• Performance Analysis: Built-in library statistics and benchmarking

Music Organization Tools

• Servify: Organize music files into Plex-compatible directory structures
• Flexible naming patterns: Customizable track and folder naming
• Dry-run mode: Preview organization before making changes
• Batch processing: Handle large libraries efficiently

Requirements

• macOS 10.7+ with iTunes Library framework
• Swift toolchain for compilation
• Python 3.10+
• Required packages: NumPy, Pandas, OpenPyXL
• Optional: Pillow (for image processing features)

Installation

Development Setup

# Clone the repository
git clone https://github.com/seantrue/musiclib.git
cd musiclib

# Check prerequisites
make check

# Build the Swift bridge
make build

# Install for development
make install-dev

Quick Test

# Run smoke tests
make smoke

# Run comprehensive demo
make demos

# Show library statistics
make export-stats

Usage

Basic Library Access

import musiclib

# Initialize library connection
library = musiclib.ITLibrary()

# Get library info
print(f"Media items: {library.media_items_count}")
print(f"Playlists: {library.playlists_count}")
print(f"Music folder: {library.music_folder_location}")

# Access media items
item = library.get_media_item(0)
print(f"Title: {item.title}")
print(f"Artist: {item.artist}")
print(f"Album: {item.album}")
print(f"Duration: {item.duration} seconds")

# Search functionality
matches = library.search_by_title("love")
print(f"Found {matches} songs with 'love' in title")

Advanced Data Export

from musiclib.helpers import LibraryBenchmark

# Export library to CSV with filtering
benchmark = LibraryBenchmark()
df = benchmark.export_library_to_dataframe(
    audio_only=True,
    limit=1000
)

# Save to various formats
df.to_csv("my_library.csv", index=False)
df.to_excel("my_library.xlsx", index=False)

Command-Line Tools

Library Export Tool

# Export entire library to CSV
musiclib-export library.csv

# Export with advanced filtering
musiclib-export filtered.csv --genre-filter rock --year-min 1990 --year-max 2000

# Export high-quality tracks to Excel
musiclib-export hq_music.xlsx --format excel --bitrate-min 256

# Show library statistics for planning
musiclib-export --stats

# Search and export specific content
musiclib-export beatles.csv --artist-search "beatles"

Music Organization Tool

# Organize music files from exported CSV
python utils/servify.py library.csv

# Preview organization without copying files
python utils/servify.py library.csv --dry-run

# Custom output directory and track naming
python utils/servify.py library.csv --output /media/music --track-format "{track:03d}. {title}"

# Force overwrite existing files
python utils/servify.py library.csv --force

# Quiet mode for scripting
python utils/servify.py library.csv --quiet

Demo and Testing

# Run smoke tests
musiclib-smoke

# Run comprehensive demos
musiclib-demo

# Run specific demo types
musiclib-demo --demos basic
musiclib-demo --demos benchmarks

Architecture

MusicLib uses a hybrid Python/Swift architecture:

1. Python Layer (src/musiclib/) - Main API, export tools, and data processing
2. Swift Bridge (src/SwiftITLibBridge.swift) - Native iTunes Library interface
3. Dynamic Library (libitlibrary.dylib) - Compiled Swift bridge for iTunes Library access
4. Command-Line Tools - Export, organization, and testing utilities

The flow is: Python → ctypes → Swift dylib → iTunes Library Framework

Project Structure

musiclib/
├── src/musiclib/          # Main Python package
│   ├── musiclib.py        # Core iTunes Library API
│   ├── helpers.py         # Export and analysis tools
│   └── scripts/           # CLI tools
│       ├── export.py      # Advanced export utility
│       ├── demo.py        # Demonstration suite
│       └── smoke.py       # Validation tests
├── utils/                 # Utility scripts
│   ├── servify.py        # Music organization tool
│   └── test_auth.py      # Authorization testing
├── src/SwiftITLibBridge.swift # Swift bridge implementation
└── tests/                # Test suite

Key Components

Core Library:

• musiclib.py - Core iTunes Library API classes (ITLibrary, MediaItem, Playlist)
• helpers.py - Data export, benchmarking, and analysis tools

Command-Line Scripts:

• scripts/export.py - Advanced data export tool with filtering (musiclib-export)
• scripts/demo.py - Comprehensive demonstration suite (musiclib-demo)
• scripts/smoke.py - Quick validation and testing (musiclib-smoke)

Utilities:

• utils/servify.py - Music file organization tool for Plex-compatible structures
• utils/test_auth.py - iTunes Library authorization testing utility

Development

Code Quality

# Format code
make format

# Run linting
make lint

# Type checking
make typecheck

# Run tests (skip slow benchmarks)
uv run pytest -m "not slow"

# Run all tests including performance benchmarks
make test

Export and Analysis

# Export sample library data
make export-sample

# Show library statistics
make export-stats

# Run performance benchmarks
make benchmark

Building and Distribution

# Clean build artifacts
make clean

# Build universal binary (ARM64 + x86_64)
make build-universal

# Create distribution package
make dist

# Install from wheel
make install

Features

Data Export Capabilities

• Comprehensive Metadata: Extract all available iTunes metadata fields
• Advanced Filtering: Multiple filter types including ranges, text search, and date filtering
• Multiple Formats: CSV, Excel, JSON, and Parquet export support
• Performance Optimized: Efficient processing of large libraries
• Progress Reporting: Real-time statistics and progress updates

Music Organization

• Plex-Compatible Structure: Organize files as Artist/Album/Track format
• Flexible Naming: Customizable track and folder naming patterns
• Safe Operations: Dry-run mode and file validation
• Cross-Platform Paths: Automatic filename sanitization
• Batch Processing: Handle thousands of files efficiently

Analysis Tools

• Library Statistics: Comprehensive analysis of your music collection
• Performance Benchmarks: Measure library access and processing speeds
• Search Analytics: Analyze search performance and results
• Data Quality: Identify missing metadata and file issues

Important Notes

• macOS Only: This library only works on macOS with the iTunes Library framework
• Permissions: May require user permission for iTunes/Music library access on first run
• Swift Compilation: The Swift bridge must be compiled before Python code can run (make build)
• Library Content: Many features depend on having media content in your iTunes/Music library
• File Access: Export and organization features require accessible file paths

CLI Commands

After installation, the following commands are available:

• musiclib-export - Advanced data export with filtering and search
• musiclib-demo - Comprehensive demonstration of library capabilities
• musiclib-smoke - Quick validation and testing
• utils/servify.py - Music file organization utility

Examples

Export Recent High-Quality Music

# Export tracks added in 2024 with high bitrate
musiclib-export recent_hq.csv \
  --date-added-after 2024-01-01 \
  --bitrate-min 256 \
  --format csv

Organize Music Library for Plex

# Export library data
musiclib-export my_library.csv

# Organize files with custom naming
python utils/servify.py my_library.csv \
  --output /media/plex-music \
  --track-format "{track:02d} - {title}" \
  --dry-run

Library Analysis

# Show comprehensive library statistics
musiclib-export --stats

# Export analysis data for external tools
musiclib-export analysis.xlsx \
  --format excel \
  --include-unrated \
  --local-only

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: make test
5. Submit a pull request

For development setup and contribution guidelines, see CLAUDE.md.