iLibrary

iLibrary prepares downloaded music for a local Apple Music library. It converts lossless downloads to Apple Lossless, applies a JSON catalog without re-encoding, arranges filenames and dates, and adds albums in a controlled order.

Note: Version 0.2.0 is experimental. Start with copies and a separate test library. iLibrary is not affiliated with, endorsed by, or sponsored by Apple.

Features

• Catalog export, authoring instructions, validation, and metadata application without audio re-encoding.
• Verified lossless conversion and M4A purchase-metadata removal.
• Consistent names and dates, ordered album addition, and file and library diagnostics.
• Dry runs, write plans, and verification for mutating commands.

Requirements

• macOS 14 or later on Apple silicon.
• npm or Python 3.9 or later for the corresponding installer. Neither is required by the installed native executable.
• Homebrew installations build from source and require Swift 6 from Xcode or the Command Line Tools.
• Music and Automation permission for library commands; no subscription is required for local processing.

The minimum OS is the deployment target; local qualification used macOS 27.0.1. Packaged binaries are ad hoc-signed, without Developer ID signing or notarization.

Qualification Limits

rebuild prepare was qualified once by the maintainer, on a synthetic library of 12 tracks on one Mac with macOS 27.0.1 and Music 1.7 and one external HFS+ backup drive. APFS backups and the refusal of partitions, disk images, and network volumes are covered by tests, not by that live run. A successful rebuild prepare shows only that the checks it reports passed for the selected files, backup, and environment at that time; it does not guarantee that a personal library or backup medium can be recovered. Keep independent backups and complete the separate-user validation before any personal-library use; iLibrary does not prevent Apple Music cloud matching.

check --library uses a bulk read only when its result is consistent and every track's cloud status is unknown, and otherwise uses the previous per-track read. In one maintainer-run comparison on a synthetic library of 12 tracks with macOS 27.0.1 and Music 1.7, its results matched those of the per-track read. Which read was used, its speed with larger libraries, and its behavior with other cloud statuses were not measured; libraries with other statuses keep the per-track read and its speed.

Installation

Choose one channel; all install the same command, ilibrary.

npm

npm install -g @x96_64/ilibrary@0.2.0
ilibrary --version

pip

Install in an isolated environment to avoid changing system Python:

python3 -m venv .venv-ilibrary
.venv-ilibrary/bin/python -m pip install x96_64-ilibrary==0.2.0
.venv-ilibrary/bin/ilibrary --version
source .venv-ilibrary/bin/activate

Homebrew

brew install x96x64/tap/ilibrary
ilibrary --version

Updating and Uninstalling

Read the changelog before updating. Use npm update -g @x96_64/ilibrary, python -m pip install --upgrade x96_64-ilibrary in the chosen environment, or brew upgrade ilibrary, respectively. Packages on npm and PyPI have different names because PyPI does not support npm scopes; neither package is named simply ilibrary.

Remove the corresponding installation with npm uninstall -g @x96_64/ilibrary, python -m pip uninstall x96_64-ilibrary, or brew uninstall ilibrary. Removing the executable does not undo file or library changes. Retain catalogs and addition journals needed for recovery.

Usage

Quick Start

Use selected copies in ./downloads and a new ./staging directory. Each write has a preview:

ilibrary import ./downloads -o ./staging --dry-run
ilibrary import ./downloads -o ./staging
ilibrary export ./staging -o catalog.json --artwork covers --dry-run
ilibrary export ./staging -o catalog.json --artwork covers
ilibrary prompt catalog.json > prompt.md
# Complete and review the catalog before applying it.
ilibrary validate catalog.json ./staging
ilibrary apply catalog.json ./staging --rename --timestamps --dry-run
ilibrary apply catalog.json ./staging --rename --timestamps
ilibrary check ./staging

For addition to Music, first follow Test Library Validation in a separate macOS user. add moves selected sources, stops at an existing matching track, confirms each album, and retains a resumption journal.

Commands

Use ilibrary help COMMAND for options. Every mutating command offers --dry-run, lists its plan, and verifies its writes. A batch is not a transaction; earlier completed files can remain after a later failure.

Verification and Limits

The public suite uses synthetic audio and substitute library adapters. The maintainer separately reported twelve successful live command checks in a test user. Qualification of 301 personal-file copies found no file diagnostic and left originals unchanged. Those results do not establish behavior on every OS version or in a cloud library.

Conversion supports integer mono and stereo PCM. Protected audio is refused. Real Trash operations remain untested. iLibrary reports cloud status but does not claim to prevent Apple Music matching. It does not download recordings or include commercial audio or artwork. Catalogs, prompts, output, and journals can contain private data; review them before sharing.

Rights

Process only recordings and artwork that you have the right to use. iLibrary does not distribute commercial recordings or store artwork. Catalogs, prompts, output, and journals can contain private metadata; review them before sharing.

Links

• README
• Command-Line Interface
• Library Operations and Recovery
• Distribution
• Support
• Current Status

License

iLibrary is licensed under the Apache License, Version 2.0.