Implement albums subcommand with release-group MBID lookup functionality

Co-authored-by: ekinnee <1707617+ekinnee@users.noreply.github.com>

Author: Copilot

AppleMusicXmlToLidarr.py

@@ -37,6 +37,32 @@ def search_musicbrainz_recording(artist: str, title: str, album: str = None) ->
         logging.warning(f"MusicBrainz lookup failed for '{artist} - {title}' ({album}): {e}")
     return ""
 
+def search_musicbrainz_release_group(artist: str, album: str) -> str:
+    """
+    Query MusicBrainz for the release-group MBID given artist and album.
+    Returns the MBID string, or empty string if not found.
+    """
+    base_url = "https://musicbrainz.org/ws/2/release-group/"
+    query = f'release:"{album}" AND artist:"{artist}"'
+    params = {
+        "query": query,
+        "fmt": "json",
+        "limit": 1
+    }
+    url = base_url + "?" + urllib.parse.urlencode(params)
+    headers = {
+        "User-Agent": "AppleMusicXmlToLidarr/1.0 (ekinnee)"
+    }
+    req = urllib.request.Request(url, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=10) as response:
+            data = json.load(response)
+            if "release-groups" in data and data["release-groups"]:
+                return data["release-groups"][0].get("id", "")
+    except Exception as e:
+        logging.warning(f"MusicBrainz release-group lookup failed for '{artist} - {album}': {e}")
+    return ""
+
 def parse_apple_music_xml(xml_path: str) -> List[Dict]:
     """
     Parse the Apple Music Library XML file and extract tracks with artist and title.
@@ -54,6 +80,31 @@ def parse_apple_music_xml(xml_path: str) -> List[Dict]:
             song_list.append({"artist": artist, "title": title, "album": album})
     return song_list
 
+def extract_unique_albums(xml_path: str) -> List[Dict]:
+    """
+    Parse the Apple Music Library XML file and extract unique (artist, album) pairs.
+    Returns a list of dicts: {artist, album}
+    """
+    with open(xml_path, "rb") as f:
+        plist = plistlib.load(f)
+    tracks = plist.get("Tracks", {})
+    
+    # Use a set to track unique combinations
+    unique_albums = set()
+    album_list = []
+    
+    for track in tracks.values():
+        artist = track.get("Artist")
+        album = track.get("Album")
+        if artist and album:
+            # Create a unique key for this artist-album combination
+            unique_key = (artist, album)
+            if unique_key not in unique_albums:
+                unique_albums.add(unique_key)
+                album_list.append({"artist": artist, "album": album})
+    
+    return album_list
+
 def build_lidarr_json(songs: List[Dict]) -> (List[Dict], List[Dict]):
     """
     For each song, lookup the MusicBrainzId and build the Lidarr-compatible dict.
@@ -71,6 +122,23 @@ def build_lidarr_json(songs: List[Dict]) -> (List[Dict], List[Dict]):
         time.sleep(1)  # MusicBrainz rate limit for anonymous requests
     return found, not_found
 
+def build_albums_json(albums: List[Dict]) -> (List[Dict], List[Dict]):
+    """
+    For each album, lookup the release-group MusicBrainzId.
+    Returns two lists: found (with MBID) and not_found (for later processing).
+    """
+    found = []
+    not_found = []
+    for idx, album in enumerate(albums, 1):
+        mbid = search_musicbrainz_release_group(album["artist"], album["album"])
+        if mbid:
+            found.append({"MusicBrainzId": mbid})
+        else:
+            not_found.append(album)
+        logging.info(f"[{idx}/{len(albums)}] {album['artist']} - {album['album']} => MBID: {mbid if mbid else 'NOT FOUND'}")
+        time.sleep(1)  # MusicBrainz rate limit for anonymous requests
+    return found, not_found
+
 def recheck_not_found(output_json: str, not_found_json: str):
     """
     Recheck items from not_found_json, append newly found MBIDs to output_json,
@@ -151,21 +219,81 @@ def main(xml_path: str, output_json: str, not_found_json: str):
         json.dump(not_found, nf, ensure_ascii=False, indent=2)
     logging.info(f"Exported {len(not_found)} unmatched tracks to {not_found_json}")
 
+def albums_main(xml_path: str, output_json: str, not_found_json: str):
+    """
+    Parse XML, extract unique albums, get release-group MBIDs, write found and not found to separate files.
+    """
+    logging.info(f"Parsing Apple Music library for albums: {xml_path}")
+    albums = extract_unique_albums(xml_path)
+    logging.info(f"Found {len(albums)} unique albums.")
+
+    found, not_found = build_albums_json(albums)
+
+    # Write found MBIDs to output JSON (for Lidarr import)
+    with open(output_json, "w", encoding="utf-8") as f:
+        json.dump(found, f, ensure_ascii=False, indent=2)
+    logging.info(f"Exported {len(found)} release-group MusicBrainzIds to {output_json}")
+
+    # Write not found items to a separate JSON file for later processing
+    with open(not_found_json, "w", encoding="utf-8") as nf:
+        json.dump(not_found, nf, ensure_ascii=False, indent=2)
+    logging.info(f"Exported {len(not_found)} unmatched albums to {not_found_json}")
+
 if __name__ == "__main__":
     import argparse
-    parser = argparse.ArgumentParser(description="Convert Apple Music Library.xml to Lidarr JSON import format with not-found items exported.")
-    parser.add_argument("--recheck", action="store_true", 
-                        help="Recheck mode: process items from not_found_json instead of parsing XML")
-    parser.add_argument("xml_file", nargs="?", help="Path to Apple Music Library.xml (not needed in recheck mode)")
-    parser.add_argument("output_json", help="Output JSON file path for found items")
-    parser.add_argument("not_found_json", help="Output JSON file path for not found items")
-    args = parser.parse_args()
+    import sys
+    
+    # Check if the first argument is a subcommand
+    has_subcommand = len(sys.argv) > 1 and sys.argv[1] in ['tracks', 'albums']
 
-    if args.recheck:
-        if args.xml_file:
-            logging.warning("XML file argument ignored in recheck mode")
-        recheck_not_found(args.output_json, args.not_found_json)
+    if has_subcommand:
+        # Use subcommands
+        parser = argparse.ArgumentParser(description="Convert Apple Music Library.xml to Lidarr JSON import format with not-found items exported.")
+        subparsers = parser.add_subparsers(dest='command', help='Available commands')
+        
+        # Tracks subcommand
+        tracks_parser = subparsers.add_parser('tracks', help='Process individual tracks (default)')
+        tracks_parser.add_argument("--recheck", action="store_true", 
+                            help="Recheck mode: process items from not_found_json instead of parsing XML")
+        tracks_parser.add_argument("xml_file", nargs="?", help="Path to Apple Music Library.xml (not needed in recheck mode)")
+        tracks_parser.add_argument("output_json", help="Output JSON file path for found items")
+        tracks_parser.add_argument("not_found_json", help="Output JSON file path for not found items")
+        
+        # Albums subcommand  
+        albums_parser = subparsers.add_parser('albums', help='Process unique albums')
+        albums_parser.add_argument("xml_file", help="Path to Apple Music Library.xml")
+        albums_parser.add_argument("output_json", help="Output JSON file path for found albums (default: albums.json)")
+        albums_parser.add_argument("not_found_json", help="Output JSON file path for not found albums (default: albums_notfound.json)")
+        
+        args = parser.parse_args()
+        
+        # Handle subcommands
+        if args.command == 'albums':
+            albums_main(args.xml_file, args.output_json, args.not_found_json)
+        elif args.command == 'tracks':
+            if args.recheck:
+                if args.xml_file:
+                    logging.warning("XML file argument ignored in recheck mode")
+                recheck_not_found(args.output_json, args.not_found_json)
+            else:
+                if not args.xml_file:
+                    tracks_parser.error("xml_file is required when not in recheck mode")
+                main(args.xml_file, args.output_json, args.not_found_json)
     else:
-        if not args.xml_file:
-            parser.error("xml_file is required when not in recheck mode")
-        main(args.xml_file, args.output_json, args.not_found_json)
+        # Backward compatibility: use original argument structure
+        parser = argparse.ArgumentParser(description="Convert Apple Music Library.xml to Lidarr JSON import format with not-found items exported.")
+        parser.add_argument("--recheck", action="store_true", 
+                            help="Recheck mode: process items from not_found_json instead of parsing XML")
+        parser.add_argument("xml_file", nargs="?", help="Path to Apple Music Library.xml (not needed in recheck mode)")
+        parser.add_argument("output_json", help="Output JSON file path for found items")
+        parser.add_argument("not_found_json", help="Output JSON file path for not found items")
+        args = parser.parse_args()
+        
+        if args.recheck:
+            if args.xml_file:
+                logging.warning("XML file argument ignored in recheck mode")
+            recheck_not_found(args.output_json, args.not_found_json)
+        else:
+            if not args.xml_file:
+                parser.error("xml_file is required when not in recheck mode")
+            main(args.xml_file, args.output_json, args.not_found_json)

README.md

@@ -4,7 +4,9 @@ Export your Apple Music Library to the default xml and feed it to this. It looks
 
 ## Usage
 
-### Initial Processing
+### Processing Individual Tracks (Default)
+
+#### Initial Processing
 Convert Apple Music Library XML to Lidarr JSON format:
 
 ```bash
@@ -17,7 +19,7 @@ This will:
 - Save found MBIDs to `found_tracks.json` for Lidarr import
 - Save unmatched tracks to `not_found_tracks.json` for later processing
 
-### Recheck Mode
+#### Recheck Mode
 Reprocess tracks that were not found initially:
 
 ```bash
@@ -30,21 +32,55 @@ This will:
 - Append any newly found MBIDs to the existing `found_tracks.json`
 - Update `not_found_tracks.json` by removing successfully matched tracks
 
+### Processing Albums
+
+Extract unique albums and get release-group MBIDs:
+
+```bash
+python3 AppleMusicXmlToLidarr.py albums Library.xml albums.json albums_notfound.json
+```
+
+This will:
+- Parse your Apple Music Library.xml file
+- Extract unique (artist, album) pairs
+- Look up MusicBrainz release-group IDs for each album
+- Save found release-group MBIDs to `albums.json` for Lidarr import
+- Save unmatched albums to `albums_notfound.json` for later processing
+
 ### Workflow
 
+#### For Individual Tracks
 1. Run initial processing to generate both found and not-found files
 2. Import the found tracks into Lidarr
 3. Periodically run recheck mode to find MBIDs for previously unmatched tracks
 4. Import any newly found tracks into Lidarr
 
-The recheck mode is useful because:
+#### For Albums
+1. Run album processing to generate release-group MBIDs
+2. Import the found albums into Lidarr as release-groups
+3. Use this approach when you want to import entire albums rather than individual tracks
+
+The recheck mode is useful for tracks because:
 - MusicBrainz database is constantly updated with new entries
 - Network issues may have caused temporary lookup failures
 - You can refine your approach or wait for better data coverage
 
+### Best Practices
+
+- **Use albums subcommand** when importing entire albums to Lidarr - this provides release-group MBIDs which are more appropriate for album-based imports
+- **Use default track processing** when you need fine-grained control over individual songs
+- **Always save both found and not-found files** to enable reprocessing later
+- **Be mindful of MusicBrainz rate limits** - the tool includes 1-second delays between requests
+- **Consider the file naming convention**: use descriptive names like `albums.json`/`albums_notfound.json` for album processing
+
 ## Output Files
 
-- **found_tracks.json**: Contains MusicBrainz IDs in Lidarr-compatible format
+### For Track Processing
+- **found_tracks.json**: Contains MusicBrainz recording IDs in Lidarr-compatible format
 - **not_found_tracks.json**: Contains track metadata for songs that couldn't be matched
 
-Both files use UTF-8 encoding and pretty-printed JSON for readability.
+### For Album Processing  
+- **albums.json**: Contains MusicBrainz release-group IDs in Lidarr-compatible format
+- **albums_notfound.json**: Contains album metadata (artist, album) for albums that couldn't be matched
+
+All files use UTF-8 encoding and pretty-printed JSON for readability.