iLibrary: v0.2.0, Catalog-Driven Music Libraries for Apple Music on macOS

The second experimental release of iLibrary, a macOS command that prepares music through a JSON catalog and adds albums to a local Apple Music library in a controlled order. This version adds backup verification and recovery records for the rebuilding of a Music library, a strict inventory export, and a bulk library read for check --library.

Important

Version 0.2.0 is experimental. Use selected copies and complete the separate-user validation before operating a personal library. Cloud matching is not prevented. iLibrary is independent software with no affiliation with Apple. Use recordings and artwork that you have the right to process, and review catalogs and reports before sharing them.

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.

Highlights

• Backup and Recovery Preparation. rebuild prepare inventories the selected files, classifies every Music registration, validates the plan with per-volume capacity, verifies a backup on separate APFS or HFS+ storage, performs a restoration test that keeps its files, confirms that the backup volume is ejected, and writes a versioned private recovery record in the workspace. rebuild status reports that record. A backup volume whose device identity is unknown is refused. Neither subcommand changes Music, the source files, or the backup.
• Strict Inventory Export. export --strict refuses, without writing, an export that is not a complete inventory: skipped paths, files dropped for a missing album tag or track number, repeated or non-consecutive disc and track numbers, inconsistent declared totals, and release dates that are not a full YYYY-MM-DD date. The non-strict export is unchanged.
• Bulk Library Read for check --library. 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. In one sequence of that comparison, the changed command took 0.700 and 0.406 seconds and the previous command about 3.3 seconds; this is consistent with, but does not establish, the use of the bulk read, and it is not a performance claim.
• Staged Rebuilding Not Implemented. The subcommands rebuild stage, rebuild clear, rebuild apply, and rebuild add are reserved; each reports that it is planned and exits with status 2. The staged rebuilding of a Music library is not implemented in this version.

Verification consists of synthetic Swift tests, continuous integration on macOS and Linux, and the maintainer-run qualifications recorded under Decisions 45 and 49 of the roadmap. These results do not establish cloud behavior, the recovery of a personal library or backup medium, or compatibility with every macOS release.

Installing and Upgrading

Install with brew install x96x64/tap/ilibrary, npm install -g @x96_64/ilibrary@0.2.0, or python -m pip install x96_64-ilibrary==0.2.0 in a Python virtual environment. Update through the same channel with brew upgrade ilibrary, npm install -g @x96_64/ilibrary@latest, or python -m pip install --upgrade x96_64-ilibrary in that environment.

Homebrew builds from source and requires Swift 6 from Xcode or the Command Line Tools. npm and PyPI install a prebuilt native executable without a Swift toolchain. Packages support macOS 14 or later on Apple silicon. The executable is signed ad hoc; Developer ID signing and notarization are not provided. Keep backups, catalogs, and resumption journals, and follow Test Library Validation before personal-library use.

Known Limitations

Real Trash behavior, notarization, and execution across every supported macOS release remain unverified. Library comparison covers the file tracks and thirteen fields exposed by the adapter. Mutating batches are not transactions, and no automatic library rollback is attempted. Protected audio (.m4p) is out of scope, and iLibrary does not download audio.

See the changelog for the complete change record and Distribution for package identities and verification. The qualification evidence is recorded in the M11 qualification results and the Decision F live comparison results. iLibrary is licensed under the Apache License, Version 2.0.

iLibrary: v0.1.0, Catalog-Driven Music Libraries for Apple Music on macOS

The first packaged preview of iLibrary, a macOS command that prepares music through a JSON catalog and adds albums to a local Apple Music library in a controlled order.

Important

Version 0.1.0 is experimental. Use selected copies and complete the separate-user validation before operating a personal library. Cloud matching is not prevented, and real Trash behavior, notarization, and execution across every supported macOS release remain unverified. iLibrary is independent software with no affiliation with Apple. Use recordings and artwork that you have the right to process, and review catalogs and reports before sharing them.

Highlights

• Catalog Workflow. export, prompt, schema, and validate prepare and check a catalog; apply writes its tags, names, and release dates, and timestamps can set existing file and folder dates independently.
• Verified Import. import converts FLAC, WAV, and AIFF to Apple Lossless with decoded PCM verification, or copies M4A without re-encoding and removes purchase metadata. Integer mono and stereo audio are supported; encrypted audio is refused.
• Ordered Music Addition. add moves selected albums into Music's media folder, confirms each album, and retains a resumption journal. check compares files and library state, and doctor reports environment problems. Mutating commands provide a dry run, state their plans, and verify their results; batches can remain partially complete after failure.
• Packages. Homebrew, npm, and PyPI distributions support macOS 14 or later on Apple silicon. All three public installation paths passed version, schema, and help checks; npm and PyPI retained the reviewed executable bytes.

Verification passed 154 synthetic Swift tests, strict formatting, and eight publication-guard tests. The maintainer reported twelve successful Music command checks in a separate macOS user. Qualification on copies of 301 files in 20 folders passed catalog export, application, arrangement, repeated application, and file diagnostics; originals retained their bytes and dates. These measurements do not establish cloud behavior or compatibility with every macOS release. See the publication report for release identity and verification evidence.

Installing and Upgrading

Install with brew install x96x64/tap/ilibrary, npm install -g @x96_64/ilibrary@0.1.0, or python -m pip install x96_64-ilibrary==0.1.0 in a Python virtual environment. Update through the same channel with brew upgrade ilibrary, npm install -g @x96_64/ilibrary@latest, or python -m pip install --upgrade x96_64-ilibrary in that environment.

Homebrew builds from source and requires Swift 6 from Xcode or the Command Line Tools. npm and PyPI install a prebuilt native executable without a Swift toolchain. The executable is signed ad hoc; Developer ID signing and notarization are not provided. Keep backups, catalogs, and resumption journals, and follow Test Library Validation before personal-library use.

See the changelog for the complete change record and Distribution for package identities and verification. iLibrary is licensed under the Apache License, Version 2.0.