Library Comparator

Command status: in refinement 🧪

Docs status: unreviewed ⚠️

This doc is 100% AI generated. I haven't had the time to refine it yet. Use with precaution.

Ease of use: 4/5 😌

Overview

The Library Comparator helps you compare two music library directories to identify differences between two folders. This tool is essential when you have multiple copies of your music collection and need to understand what's different between them.

What it does:

Finds files that exist in one library but not the other
Identifies files with different sizes (different versions/qualities)
Detects files with identical sizes but different content
Spots "upscaled" files (low-quality audio converted to appear high-quality)
Optionally removes upscaled files

Why you'd use it:

Compare backup libraries with your main collection
Identify which files need to be synced between different storage locations
Clean up duplicate libraries after reorganizing your music
Remove fake high-quality files that are just wasting space

Parameters

Required Parameters

Library A Path

The first music library directory to compare
Example: /Users/dj/Music/Library1 or D:\Music\MainLibrary
Must be an existing directory with audio files

Library B Path

The second music library directory to compare
Example: /Users/dj/Music/Library2 or D:\Music\BackupLibrary
Must be an existing directory with audio files
Cannot be the same directory as Library A

Optional Parameters

Export Results to File

Save a detailed comparison report to a text file
Leave empty to skip report generation
Example: /Users/dj/Desktop/library_comparison_report.md
Creates a markdown file with complete comparison results

Delete Upscaled Files

Check this box to automatically remove detected upscaled files from Library B
Use with caution - this will permanently delete files!
Only deletes files identified as "upscaled" (fake high-quality conversions)

Step-by-Step Process

1. Directory Scanning

The tool first scans both library directories to find all audio files. You'll see progress spinners showing how many files are found in each library.

2. File Structure Comparison

The tool creates a map of all files in each library and compares them. It looks for:

Files that exist in Library A but not Library B
Files that exist in Library B but not Library A
Files with the same name but different sizes
Files with identical sizes but different audio content

3. Upscaling Detection

The tool analyzes files that exist in both libraries to detect "upscaled" audio. These are files where someone has taken a low-quality audio file (like 128 kbps MP3) and converted it to a higher bitrate (like 320 kbps) to make it appear higher quality.

How it detects upscaling:

Compares the theoretical bitrate between versions
Flags files where Library B version has 1.5x higher bitrate AND exceeds 320 kbps
Calculates the size increase and bitrate difference

4. Results Display

The tool displays a comprehensive summary showing:

Total files in each library
Missing files in each direction
Files with size differences
Files with identical sizes but different content
Upscaled files detected (with before/after quality info)

5. Optional Cleanup

If you enabled "Delete Upscaled Files," the tool will remove the detected upscaled files from Library B, showing you which files were deleted and any errors encountered.

6. Report Export (Optional)

If you specified an export file, the tool creates a detailed markdown report with all findings, saved to your specified location.

Impact on Files

What remains unchanged:

Library A is never modified in any way
Library B files remain unchanged (except optional upscaled file deletion)
No files are renamed, moved, or converted
Original file metadata is preserved

What gets created:

Optional comparison report file (markdown format)
Console output with comparison results

What gets deleted (only if you enable it):

Upscaled files from Library B (permanent deletion)

No data loss occurs unless you explicitly enable the upscaled file deletion option.

Safety Notes & Recovery

Built-in Safety Features

Directory Validation: Ensures both library paths exist before starting
Self-Comparison Prevention: Won't let you compare a directory to itself
Progress Tracking: Shows clear progress indicators during long operations
Graceful Error Handling: Continues processing even if individual files fail
Optional Deletion: Upscaling removal is disabled by default - you must explicitly enable it

Before Running

Verify your paths - Double-check that Library A and Library B are correct
Consider a test run - First run without deletion to see what would be removed
Backup important libraries - Especially if planning to delete upscaled files

If Something Goes Wrong

Comparison Stops: Check the error messages displayed - usually file permission issues
Upscaled Deletion Errors: Files may be locked by other applications
Missing Expected Files: Ensure both libraries are fully accessible and not corrupted

Recovery Options

Deleted Files: If you accidentally deleted upscaled files, you'll need to restore from backup
Incomplete Comparison: Simply run the tool again - it will pick up where it left off
Wrong Comparison: Re-run with correct library paths

Summary

The Library Comparator is a safe, comprehensive tool for analyzing differences between music libraries. It provides detailed insights into what's different between your collections without modifying anything unless you explicitly request it.

Key benefits:

No Risk: Default operation is read-only - no files are changed
Detailed Analysis: Finds all types of differences, not just missing files
Quality Detection: Identifies fake high-quality files that waste space
Progress Tracking: Clear feedback on what's happening during long operations
Comprehensive Reporting: Detailed results with optional export for later reference

Your music collection remains completely safe during comparison. Only enable file deletion after carefully reviewing the detected upscaled files and ensuring you have appropriate backups.