From ac3bf51c56b79f2eb9bd8067927ee087a0de0fa7 Mon Sep 17 00:00:00 2001
From: Winman486 <harpsystems@gmail.com>
Date: Fri, 17 Oct 2025 15:17:02 -0500
Subject: [PATCH 1/4] feat(gui): add 'Download Full Album', 'Download All
 Albums', and 'Single album folder (primary artist)' preference

---
 tidal_dl_ng/dialog.py             |   1 +
 tidal_dl_ng/download.py           |   4 +
 tidal_dl_ng/gui.py                | 169 +++++++++++++++++++++++++++++-
 tidal_dl_ng/helper/path.py        |  22 +++-
 tidal_dl_ng/model/cfg.py          |   2 +
 tidal_dl_ng/ui/dialog_settings.py |  11 +-
 6 files changed, 204 insertions(+), 5 deletions(-)

diff --git a/tidal_dl_ng/dialog.py b/tidal_dl_ng/dialog.py
index b17c151..8b194f4 100644
--- a/tidal_dl_ng/dialog.py
+++ b/tidal_dl_ng/dialog.py
@@ -175,6 +175,7 @@ class DialogPreferences(QtWidgets.QDialog):
         self.parameters_checkboxes = [
             "lyrics_embed",
             "lyrics_file",
+            "use_primary_album_artist",
             "video_download",
             "download_delay",
             "video_convert_mp4",
diff --git a/tidal_dl_ng/download.py b/tidal_dl_ng/download.py
index 4ac2b14..f0bb883 100644
--- a/tidal_dl_ng/download.py
+++ b/tidal_dl_ng/download.py
@@ -663,6 +663,7 @@ class Download:
             list_total,
             delimiter_artist=self.settings.data.filename_delimiter_artist,
             delimiter_album_artist=self.settings.data.filename_delimiter_album_artist,
+            use_primary_album_artist=self.settings.data.use_primary_album_artist,
         )
 
         path_media_dst: pathlib.Path = (
@@ -685,6 +686,7 @@ class Download:
                     media,
                     delimiter_artist=self.settings.data.filename_delimiter_artist,
                     delimiter_album_artist=self.settings.data.filename_delimiter_album_artist,
+                    use_primary_album_artist=self.settings.data.use_primary_album_artist,
                 )
                 path_media_track_dir: pathlib.Path = (
                     pathlib.Path(self.path_base).expanduser() / (file_name_track_dir_relative + file_extension_dummy)
@@ -966,6 +968,7 @@ class Download:
             media,
             delimiter_artist=self.settings.data.filename_delimiter_artist,
             delimiter_album_artist=self.settings.data.filename_delimiter_album_artist,
+            use_primary_album_artist=self.settings.data.use_primary_album_artist,
         )
         path_media_dst: pathlib.Path = (
             pathlib.Path(self.path_base).expanduser() / (file_name_relative + file_extension)
@@ -1352,6 +1355,7 @@ class Download:
             media,
             delimiter_artist=self.settings.data.filename_delimiter_artist,
             delimiter_album_artist=self.settings.data.filename_delimiter_album_artist,
+            use_primary_album_artist=self.settings.data.use_primary_album_artist,
         )
 
         # Get the name of the list and check, if videos should be included.
diff --git a/tidal_dl_ng/gui.py b/tidal_dl_ng/gui.py
index d27f2b6..7449fa0 100644
--- a/tidal_dl_ng/gui.py
+++ b/tidal_dl_ng/gui.py
@@ -401,6 +401,7 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
         if hasattr(header, "setSectionResizeMode"):
             header.setSectionResizeMode(0, QtWidgets.QHeaderView.ResizeToContents)
         tree.setContextMenuPolicy(QtCore.Qt.CustomContextMenu)
+        tree.customContextMenuRequested.connect(self.menu_context_queue_download)
 
     def tidal_user_lists(self) -> None:
         """Fetch and emit user playlists, mixes, and favorites from Tidal."""
@@ -565,6 +566,7 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
         menu = QtWidgets.QMenu()
         menu.addAction("Download Playlist", lambda: self.thread_download_list_media(point))
         menu.addAction("Copy Share URL", lambda: self.on_copy_url_share(self.tr_lists_user, point))
+        menu.addAction("Download All Albums", lambda: self.thread_it(self.on_download_all_albums_from_playlist, point))
 
         menu.exec(self.tr_lists_user.mapToGlobal(point))
 
@@ -581,12 +583,55 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
         if not index.isValid():
             return
 
+        # Get the media item at this point
+        media = get_results_media_item(index, self.proxy_tr_results, self.model_tr_results)
+
         # We build the menu.
         menu = QtWidgets.QMenu()
         menu.addAction("Copy Share URL", lambda: self.on_copy_url_share(self.tr_results, point))
 
+        # Add "Download Full Album" option if it's a track or video with an album
+        if isinstance(media, (Track, Video)) and hasattr(media, "album") and media.album:
+            menu.addAction("Download Full Album", lambda: self.thread_it(self.on_download_album_from_track, point))
+
         menu.exec(self.tr_results.mapToGlobal(point))
 
+    def menu_context_queue_download(self, point: QtCore.QPoint) -> None:
+        """Show context menu for download queue.
+
+        Args:
+            point (QPoint): The point where the menu is requested.
+        """
+        # Get the item at this point
+        item = self.tr_queue_download.itemAt(point)
+
+        if not item:
+            return
+
+        # Build the menu
+        menu = QtWidgets.QMenu()
+
+        # Show remove option for waiting items
+        status = item.text(0)
+        if status == QueueDownloadStatus.Waiting:
+            menu.addAction("🗑️ Remove from Queue", lambda: self.on_queue_download_remove_item(item))
+
+        if menu.isEmpty():
+            return
+
+        menu.exec(self.tr_queue_download.mapToGlobal(point))
+
+    def on_queue_download_remove_item(self, item: QtWidgets.QTreeWidgetItem) -> None:
+        """Remove a specific item from the download queue.
+        
+        Args:
+            item (QTreeWidgetItem): The item to remove.
+        """
+        index = self.tr_queue_download.indexOfTopLevelItem(item)
+        if index >= 0:
+            self.tr_queue_download.takeTopLevelItem(index)
+            logger_gui.info("Removed item from download queue")
+
     def thread_download_list_media(self, point: QtCore.QPoint) -> None:
         """Start download of a list media item in a thread.
 
@@ -595,6 +640,127 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
         """
         self.thread_it(self.on_download_list_media, point)
 
+    def on_download_all_albums_from_playlist(self, point: QtCore.QPoint) -> None:
+        """Download all unique albums from tracks in a playlist.
+        
+        Args:
+            point (QPoint): The point in the tree where the playlist was right-clicked.
+        """
+        try:
+            # Get the playlist
+            item = self.tr_lists_user.itemAt(point)
+            media_list = get_user_list_media_item(item)
+            
+            if not isinstance(media_list, (Playlist, UserPlaylist, Mix)):
+                logger_gui.error("Please select a playlist or mix.")
+                return
+            
+            # Get all items from the playlist
+            logger_gui.info(f"Fetching all tracks from: {media_list.name}")
+            media_items = items_results_all(media_list)
+            
+            # Extract unique albums from tracks
+            albums_dict = {}
+            for media_item in media_items:
+                if isinstance(media_item, (Track, Video)) and hasattr(media_item, 'album') and media_item.album:
+                    # Reload full album object
+                    album = self.tidal.session.album(media_item.album.id)
+                    albums_dict[album.id] = album
+            
+            if not albums_dict:
+                logger_gui.warning("No albums found in this playlist.")
+                return
+            
+            # Prepare all queue items first
+            logger_gui.info(f"Found {len(albums_dict)} unique albums. Preparing queue items...")
+            
+            queue_items = []
+            for album in albums_dict.values():
+                queue_dl_item = self.media_to_queue_download_model(album)
+                if queue_dl_item:
+                    queue_items.append((queue_dl_item, album))
+                    logger_gui.debug(f"Prepared: {name_builder_artist(album)} - {album.name}")
+            
+            # Add all items to queue at once
+            logger_gui.info(f"Adding {len(queue_items)} albums to queue...")
+            for queue_dl_item, album in queue_items:
+                self.queue_download_media(queue_dl_item)
+                logger_gui.info(f"Added: {name_builder_artist(album)} - {album.name}")
+            
+            # Show confirmation
+            message = f"Added {len(queue_items)} albums to download queue"
+            self.s_statusbar_message.emit(StatusbarMessage(message=message, timeout=3000))
+            logger_gui.info(message)
+            
+        except Exception as e:
+            error_msg = f"Error downloading albums from playlist: {str(e)}"
+            logger_gui.error(error_msg)
+            self.s_statusbar_message.emit(StatusbarMessage(message=error_msg, timeout=3000))
+
+    def on_download_album_from_track(self, point: QtCore.QPoint) -> None:
+        """Download the full album from a selected track.
+
+        Args:
+            point (QPoint): The point in the tree where the track was right-clicked.
+        """
+        try:
+            # Get the selected track/video
+            index = self.tr_results.indexAt(point)
+            
+            if not index.isValid():
+                logger_gui.error("Invalid selection.")
+                return
+            
+            # Get the media item (Track or Video)
+            media = get_results_media_item(index, self.proxy_tr_results, self.model_tr_results)
+            
+            # Verify it's a Track or Video with an album
+            if not isinstance(media, (Track, Video)):
+                logger_gui.error("Selected item is not a track or video.")
+                return
+            
+            if not hasattr(media, 'album') or not media.album:
+                logger_gui.error("Selected track does not have an associated album.")
+                return
+            
+            # Get the album
+            album = media.album
+            
+            # Reload the complete album object from TIDAL's API
+            album = self.tidal.session.album(album.id)
+            
+            # Debug logging for album object
+            logger_gui.info(f"Album object: {album}")
+            logger_gui.info(f"Album name: {album.name}")
+            logger_gui.info(f"Album ID: {album.id}")
+            logger_gui.info(f"Album available: {getattr(album, 'available', 'unknown')}")
+            
+            # Create a queue download item for the album
+            queue_dl_item = self.media_to_queue_download_model(album)
+            
+            if queue_dl_item:
+                # Add to download queue
+                self.queue_download_media(queue_dl_item)
+                
+                # Show confirmation message
+                artist_name = name_builder_artist(album)
+                message = f"Album added to queue: {artist_name} - {album.name}"
+                
+                self.s_statusbar_message.emit(
+                    StatusbarMessage(message=message, timeout=3000)
+                )
+                
+                logger_gui.info(message)
+            else:
+                logger_gui.error(f"Unable to add album to queue: {album.name}")
+                
+        except Exception as e:
+            error_msg = f"Error downloading album from track: {str(e)}"
+            logger_gui.error(error_msg)
+            self.s_statusbar_message.emit(
+                StatusbarMessage(message=error_msg, timeout=3000)
+            )
+
     def on_copy_url_share(
         self, tree_target: QtWidgets.QTreeWidget | QtWidgets.QTreeView, point: QtCore.QPoint = None
     ) -> None:
@@ -1042,7 +1208,8 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
         explicit: str = ""
 
         # Check if item is available on TIDAL.
-        if hasattr(media, "available") and not media.available:
+        # Note: Some albums have available=None, which should be treated as available
+        if hasattr(media, "available") and media.available is False:
             return False
 
         # Set "Explicit" tag
diff --git a/tidal_dl_ng/helper/path.py b/tidal_dl_ng/helper/path.py
index 2e83970..f83e5b7 100644
--- a/tidal_dl_ng/helper/path.py
+++ b/tidal_dl_ng/helper/path.py
@@ -89,6 +89,7 @@ def format_path_media(
     list_total: int = 0,
     delimiter_artist: str = ", ",
     delimiter_album_artist: str = ", ",
+    use_primary_album_artist: bool = False,
 ) -> str:
     """Formats a media path string using a template and media attributes.
 
@@ -102,6 +103,7 @@ def format_path_media(
         list_total (int, optional): Total items in a list. Defaults to 0.
         delimiter_artist (str, optional): Delimiter for artist names. Defaults to ", ".
         delimiter_album_artist (str, optional): Delimiter for album artist names. Defaults to ", ".
+        use_primary_album_artist (bool, optional): If True, uses first album artist for folder paths. Defaults to False.
 
     Returns:
         str: The formatted and sanitized media path string.
@@ -122,6 +124,7 @@ def format_path_media(
             list_total,
             delimiter_artist=delimiter_artist,
             delimiter_album_artist=delimiter_album_artist,
+            use_primary_album_artist=use_primary_album_artist,
         )
 
         if result_fmt != match.group(1):
@@ -143,6 +146,7 @@ def format_str_media(
     list_total: int = 0,
     delimiter_artist: str = ", ",
     delimiter_album_artist: str = ", ",
+    use_primary_album_artist: bool = False,
 ) -> str:
     """Formats a string for media attributes based on the provided name.
 
@@ -156,6 +160,7 @@ def format_str_media(
         list_total (int, optional): Total items in a list. Defaults to 0.
         delimiter_artist (str, optional): Delimiter for artist names. Defaults to ", ".
         delimiter_album_artist (str, optional): Delimiter for album artist names. Defaults to ", ".
+        use_primary_album_artist (bool, optional): If True, uses first album artist for folder paths. Defaults to False.
 
     Returns:
         str: The formatted string for the media attribute, or the original name if no formatter matches.
@@ -179,6 +184,7 @@ def format_str_media(
                 list_total,
                 delimiter_artist=delimiter_artist,
                 delimiter_album_artist=delimiter_album_artist,
+                use_primary_album_artist=use_primary_album_artist,
             )
             if result is not None:
                 return result
@@ -195,6 +201,7 @@ def _format_artist_names(
     delimiter_artist: str = ", ",
     delimiter_album_artist: str = ", ",
     *_args,
+    use_primary_album_artist: bool = False,
     **kwargs,
 ) -> str | None:
     """Handle artist name-related format strings.
@@ -202,12 +209,19 @@ def _format_artist_names(
     Args:
         name (str): The format string name to check.
         media (Track | Album | Playlist | UserPlaylist | Video | Mix): The media object to extract artist information from.
+        delimiter_artist (str, optional): Delimiter for artist names. Defaults to ", ".
+        delimiter_album_artist (str, optional): Delimiter for album artist names. Defaults to ", ".
+        use_primary_album_artist (bool, optional): If True, uses first album artist for folder paths. Defaults to False.
         *_args (Any): Additional arguments (not used).
 
     Returns:
         str | None: The formatted artist name or None if the format string is not artist-related.
     """
     if name == "artist_name" and isinstance(media, Track | Video):
+        # For folder paths, use album artist if setting is enabled
+        if use_primary_album_artist and hasattr(media, 'album') and media.album and media.album.artists:
+            return media.album.artists[0].name
+        # Otherwise use track artists as before
         if hasattr(media, "artists"):
             return name_builder_artist(media, delimiter=delimiter_artist)
         elif hasattr(media, "artist"):
@@ -252,6 +266,7 @@ def _format_names(
     *args,
     delimiter_artist: str = ", ",
     delimiter_album_artist: str = ", ",
+    use_primary_album_artist: bool = False,
     **kwargs,
 ) -> str | None:
     """Handles name-related format strings for media.
@@ -264,13 +279,18 @@ def _format_names(
         *args: Additional arguments (not used).
         delimiter_artist (str, optional): Delimiter for artist names. Defaults to ", ".
         delimiter_album_artist (str, optional): Delimiter for album artist names. Defaults to ", ".
+        use_primary_album_artist (bool, optional): If True, uses first album artist for folder paths. Defaults to False.
 
     Returns:
         str | None: The formatted name or None if the format string is not name-related.
     """
     # First try artist name formats
     result = _format_artist_names(
-        name, media, delimiter_artist=delimiter_artist, delimiter_album_artist=delimiter_album_artist
+        name,
+        media,
+        delimiter_artist=delimiter_artist,
+        delimiter_album_artist=delimiter_album_artist,
+        use_primary_album_artist=use_primary_album_artist,
     )
     if result is not None:
         return result
diff --git a/tidal_dl_ng/model/cfg.py b/tidal_dl_ng/model/cfg.py
index bee2876..4797fb5 100644
--- a/tidal_dl_ng/model/cfg.py
+++ b/tidal_dl_ng/model/cfg.py
@@ -12,6 +12,7 @@ class Settings:
     skip_existing: bool = True
     lyrics_embed: bool = False
     lyrics_file: bool = False
+    use_primary_album_artist: bool = False  # When True, uses first album artist instead of track artists for folder paths
     # TODO: Implement API KEY selection.
     # api_key_index: bool = 0
     # TODO: Implement album info download to separate file.
@@ -63,6 +64,7 @@ class HelpSettings:
     skip_existing: str = "Skip download if file already exists."
     album_cover_save: str = "Safe cover to album folder."
     lyrics_embed: str = "Embed lyrics in audio file, if lyrics are available."
+    use_primary_album_artist: str = "Use only the primary album artist for folder paths instead of track artists."
     lyrics_file: str = "Save lyrics to separate *.lrc file, if lyrics are available."
     api_key_index: str = "Set the device API KEY."
     album_info_save: str = "Save album info to track?"
diff --git a/tidal_dl_ng/ui/dialog_settings.py b/tidal_dl_ng/ui/dialog_settings.py
index 3098817..07fd217 100644
--- a/tidal_dl_ng/ui/dialog_settings.py
+++ b/tidal_dl_ng/ui/dialog_settings.py
@@ -187,10 +187,14 @@ class Ui_DialogSettings:
 
         self.horizontalLayout_12.addLayout(self.lv_playlist_create)
 
-        self.verticalLayout_4 = QVBoxLayout()
-        self.verticalLayout_4.setObjectName("verticalLayout_4")
+        self.lv_flag_use_primary_album_artist = QVBoxLayout()
+        self.lv_flag_use_primary_album_artist.setObjectName("lv_flag_use_primary_album_artist")
+        self.cb_use_primary_album_artist = QCheckBox(self.gb_flags)
+        self.cb_use_primary_album_artist.setObjectName("cb_use_primary_album_artist")
 
-        self.horizontalLayout_12.addLayout(self.verticalLayout_4)
+        self.lv_flag_use_primary_album_artist.addWidget(self.cb_use_primary_album_artist)
+
+        self.horizontalLayout_12.addLayout(self.lv_flag_use_primary_album_artist)
 
         self.lv_flags.addLayout(self.horizontalLayout_12)
 
@@ -591,6 +595,7 @@ class Ui_DialogSettings:
         # endif // QT_CONFIG(whatsthis)
         self.cb_lyrics_embed.setText(QCoreApplication.translate("DialogSettings", "CheckBox", None))
         self.cb_lyrics_file.setText(QCoreApplication.translate("DialogSettings", "CheckBox", None))
+        self.cb_use_primary_album_artist.setText(QCoreApplication.translate("DialogSettings", "CheckBox", None))
         self.cb_download_delay.setText(QCoreApplication.translate("DialogSettings", "CheckBox", None))
         self.cb_extract_flac.setText(QCoreApplication.translate("DialogSettings", "CheckBox", None))
         self.cb_metadata_cover_embed.setText(QCoreApplication.translate("DialogSettings", "CheckBox", None))

From 90ff7ea52ef7dd3c02afc313da4682b1fcb799eb Mon Sep 17 00:00:00 2001
From: Winman486 <harpsystems@gmail.com>
Date: Fri, 17 Oct 2025 23:40:31 -0500
Subject: [PATCH 2/4] feat(gui): add rate limiting to Download All Albums
 feature - Process 20 albums at a time with 3-second delays - Add session
 validity checks to prevent OAuth errors - Handle unavailable albums
 gracefully - Add informative logging for rate limiting progress

---
 tidal_dl_ng/gui.py | 56 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/tidal_dl_ng/gui.py b/tidal_dl_ng/gui.py
index 7449fa0..3b21df3 100644
--- a/tidal_dl_ng/gui.py
+++ b/tidal_dl_ng/gui.py
@@ -659,20 +659,62 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
             logger_gui.info(f"Fetching all tracks from: {media_list.name}")
             media_items = items_results_all(media_list)
             
-            # Extract unique albums from tracks
-            albums_dict = {}
+            # Extract unique album IDs from tracks
+            album_ids = {}
             for media_item in media_items:
                 if isinstance(media_item, (Track, Video)) and hasattr(media_item, 'album') and media_item.album:
-                    # Reload full album object
-                    album = self.tidal.session.album(media_item.album.id)
-                    albums_dict[album.id] = album
+                    try:
+                        # Access album.id carefully as it might trigger API calls
+                        album_id = media_item.album.id
+                        if album_id:
+                            album_ids[album_id] = media_item.album
+                    except Exception as e:
+                        logger_gui.debug(f"Skipping track with unavailable album: {str(e)}")
+                        continue
             
-            if not albums_dict:
+            if not album_ids:
                 logger_gui.warning("No albums found in this playlist.")
                 return
             
+            logger_gui.info(f"Found {len(album_ids)} unique albums. Loading with rate limiting...")
+            
+            # Load albums with rate limiting
+            albums_dict = {}
+            for idx, (album_id, album_stub) in enumerate(album_ids.items(), start=1):
+                try:
+                    # Add delay every 20 albums to avoid rate limiting
+                    if idx > 1 and (idx - 1) % 20 == 0:
+                        logger_gui.info(f"🛑 RATE LIMITING: Processed {idx - 1} albums, pausing for 3 seconds...")
+                        time.sleep(3)
+                    
+                    # Check session validity before making API calls
+                    if not self.tidal.session.check_login():
+                        logger_gui.error("Session expired. Please restart the application and login again.")
+                        return
+                    
+                    # Reload full album object
+                    album = self.tidal.session.album(album_id)
+                    albums_dict[album.id] = album
+                    logger_gui.debug(f"Loaded album {idx}/{len(album_ids)}: {name_builder_artist(album)} - {album.name}")
+                    
+                except Exception as e:
+                    error_msg = str(e)
+                    # Check for OAuth/authentication errors
+                    if "401" in error_msg or "OAuth" in error_msg or "token" in error_msg.lower():
+                        logger_gui.error(f"Authentication error: {error_msg}")
+                        logger_gui.error("Your session has expired. Please restart the application and login again.")
+                        self.s_statusbar_message.emit(StatusbarMessage(message="Session expired - please restart and login", timeout=5000))
+                        return
+                    logger_gui.warning(f"Failed to load album {album_id}: {error_msg}")
+                    logger_gui.info("Note: Some albums may be unavailable due to region restrictions or removal from TIDAL. This is normal.")
+                    continue
+            
+            if not albums_dict:
+                logger_gui.error("Failed to load any albums from playlist.")
+                return
+            
             # Prepare all queue items first
-            logger_gui.info(f"Found {len(albums_dict)} unique albums. Preparing queue items...")
+            logger_gui.info(f"Successfully loaded {len(albums_dict)} albums. Preparing queue items...")
             
             queue_items = []
             for album in albums_dict.values():

From 6c1704e3c466e043acf6afcb7929b27d131df92f Mon Sep 17 00:00:00 2001
From: Winman486 <harpsystems@gmail.com>
Date: Mon, 20 Oct 2025 18:58:46 -0500
Subject: [PATCH 3/4] fix: Remove duplicate menu entry and reduce code
 complexity

- Removed duplicate 'Download Full Album' context menu entry
- Refactored on_download_all_albums_from_playlist to reduce C901 complexity
- Extracted helper methods: _extract_album_ids_from_tracks, _load_albums_with_rate_limiting, _validate_session, _handle_album_load_error, _queue_loaded_albums
- All make check errors and warnings now resolved
---
 tidal_dl_ng/gui.py | 202 +++++++++++++++++++++++++++++----------------
 1 file changed, 132 insertions(+), 70 deletions(-)

diff --git a/tidal_dl_ng/gui.py b/tidal_dl_ng/gui.py
index 0dc319d..4bf0f06 100644
--- a/tidal_dl_ng/gui.py
+++ b/tidal_dl_ng/gui.py
@@ -588,16 +588,12 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
 
         # We build the menu.
         menu = QtWidgets.QMenu()
-        media = get_results_media_item(index, self.proxy_tr_results, self.model_tr_results)
-
-        if isinstance(media, Track) and media.album:
-            menu.addAction("Download Full Album", lambda: self.thread_download_album_from_track(point))
-
-        menu.addAction("Copy Share URL", lambda: self.on_copy_url_share(self.tr_results, point))
 
         # Add "Download Full Album" option if it's a track or video with an album
         if isinstance(media, Track | Video) and hasattr(media, "album") and media.album:
-            menu.addAction("Download Full Album", lambda: self.thread_it(self.on_download_album_from_track, point))
+            menu.addAction("Download Full Album", lambda: self.thread_download_album_from_track(point))
+
+        menu.addAction("Copy Share URL", lambda: self.on_copy_url_share(self.tr_results, point))
 
         menu.exec(self.tr_results.mapToGlobal(point))
 
@@ -652,7 +648,7 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
             point (QPoint): The point in the tree where the playlist was right-clicked.
         """
         try:
-            # Get the playlist
+            # Get and validate the playlist
             item = self.tr_lists_user.itemAt(point)
             media_list = get_user_list_media_item(item)
 
@@ -665,17 +661,7 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
             media_items = items_results_all(media_list)
 
             # Extract unique album IDs from tracks
-            album_ids = {}
-            for media_item in media_items:
-                if isinstance(media_item, Track | Video) and hasattr(media_item, "album") and media_item.album:
-                    try:
-                        # Access album.id carefully as it might trigger API calls
-                        album_id = media_item.album.id
-                        if album_id:
-                            album_ids[album_id] = media_item.album
-                    except Exception as e:
-                        logger_gui.debug(f"Skipping track with unavailable album: {e!s}")
-                        continue
+            album_ids = self._extract_album_ids_from_tracks(media_items)
 
             if not album_ids:
                 logger_gui.warning("No albums found in this playlist.")
@@ -684,64 +670,17 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
             logger_gui.info(f"Found {len(album_ids)} unique albums. Loading with rate limiting...")
 
             # Load albums with rate limiting
-            albums_dict = {}
-            for idx, album_id in enumerate(album_ids.keys(), start=1):
-                try:
-                    # Add delay every 20 albums to avoid rate limiting
-                    if idx > 1 and (idx - 1) % 20 == 0:
-                        logger_gui.info(f"🛑 RATE LIMITING: Processed {idx - 1} albums, pausing for 3 seconds...")
-                        time.sleep(3)
-
-                    # Check session validity before making API calls
-                    if not self.tidal.session.check_login():
-                        logger_gui.error("Session expired. Please restart the application and login again.")
-                        return
-
-                    # Reload full album object
-                    album = self.tidal.session.album(album_id)
-                    albums_dict[album.id] = album
-                    logger_gui.debug(
-                        f"Loaded album {idx}/{len(album_ids)}: {name_builder_artist(album)} - {album.name}"
-                    )
-
-                except Exception as e:
-                    error_msg = str(e)
-                    # Check for OAuth/authentication errors
-                    if "401" in error_msg or "OAuth" in error_msg or "token" in error_msg.lower():
-                        logger_gui.error(f"Authentication error: {error_msg}")
-                        logger_gui.error("Your session has expired. Please restart the application and login again.")
-                        self.s_statusbar_message.emit(
-                            StatusbarMessage(message="Session expired - please restart and login", timeout=5000)
-                        )
-                        return
-                    logger_gui.warning(f"Failed to load album {album_id}: {error_msg}")
-                    logger_gui.info(
-                        "Note: Some albums may be unavailable due to region restrictions or removal from TIDAL. This is normal."
-                    )
-                    continue
+            albums_dict = self._load_albums_with_rate_limiting(album_ids)
 
             if not albums_dict:
                 logger_gui.error("Failed to load any albums from playlist.")
                 return
 
-            # Prepare all queue items first
-            logger_gui.info(f"Successfully loaded {len(albums_dict)} albums. Preparing queue items...")
-
-            queue_items = []
-            for album in albums_dict.values():
-                queue_dl_item = self.media_to_queue_download_model(album)
-                if queue_dl_item:
-                    queue_items.append((queue_dl_item, album))
-                    logger_gui.debug(f"Prepared: {name_builder_artist(album)} - {album.name}")
-
-            # Add all items to queue at once
-            logger_gui.info(f"Adding {len(queue_items)} albums to queue...")
-            for queue_dl_item, album in queue_items:
-                self.queue_download_media(queue_dl_item)
-                logger_gui.info(f"Added: {name_builder_artist(album)} - {album.name}")
+            # Prepare and queue albums
+            self._queue_loaded_albums(albums_dict)
 
             # Show confirmation
-            message = f"Added {len(queue_items)} albums to download queue"
+            message = f"Added {len(albums_dict)} albums to download queue"
             self.s_statusbar_message.emit(StatusbarMessage(message=message, timeout=3000))
             logger_gui.info(message)
 
@@ -750,6 +689,129 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
             logger_gui.error(error_msg)
             self.s_statusbar_message.emit(StatusbarMessage(message=error_msg, timeout=3000))
 
+    def _extract_album_ids_from_tracks(self, media_items: list) -> dict[int, Album]:
+        """Extract unique album IDs from a list of media items.
+
+        Args:
+            media_items (list): List of media items (tracks/videos) from a playlist.
+
+        Returns:
+            dict[int, Album]: Dictionary mapping album IDs to album stub objects.
+        """
+        album_ids = {}
+
+        for media_item in media_items:
+            if not isinstance(media_item, Track | Video):
+                continue
+
+            if not hasattr(media_item, "album") or not media_item.album:
+                continue
+
+            try:
+                # Access album.id carefully as it might trigger API calls
+                album_id = media_item.album.id
+                if album_id:
+                    album_ids[album_id] = media_item.album
+            except Exception as e:
+                logger_gui.debug(f"Skipping track with unavailable album: {e!s}")
+                continue
+
+        return album_ids
+
+    def _load_albums_with_rate_limiting(self, album_ids: dict[int, Album]) -> dict[int, Album]:
+        """Load full album objects with rate limiting to prevent API throttling.
+
+        Args:
+            album_ids (dict[int, Album]): Dictionary of album IDs to album stubs.
+
+        Returns:
+            dict[int, Album]: Dictionary of successfully loaded full album objects.
+        """
+        albums_dict = {}
+
+        for idx, album_id in enumerate(album_ids.keys(), start=1):
+            try:
+                # Add delay every 20 albums to avoid rate limiting
+                if idx > 1 and (idx - 1) % 20 == 0:
+                    logger_gui.info(f"🛑 RATE LIMITING: Processed {idx - 1} albums, pausing for 3 seconds...")
+                    time.sleep(3)
+
+                # Check session validity before making API calls
+                if not self._validate_session():
+                    return albums_dict
+
+                # Reload full album object
+                album = self.tidal.session.album(album_id)
+                albums_dict[album.id] = album
+                logger_gui.debug(f"Loaded album {idx}/{len(album_ids)}: {name_builder_artist(album)} - {album.name}")
+
+            except Exception as e:
+                if not self._handle_album_load_error(e, album_id):
+                    return albums_dict
+                continue
+
+        logger_gui.info(f"Successfully loaded {len(albums_dict)} albums.")
+        return albums_dict
+
+    def _validate_session(self) -> bool:
+        """Validate that the TIDAL session is still authenticated.
+
+        Returns:
+            bool: True if session is valid, False otherwise.
+        """
+        if not self.tidal.session.check_login():
+            logger_gui.error("Session expired. Please restart the application and login again.")
+            return False
+        return True
+
+    def _handle_album_load_error(self, error: Exception, album_id: int) -> bool:
+        """Handle errors that occur when loading an album.
+
+        Args:
+            error (Exception): The exception that was raised.
+            album_id (int): The ID of the album that failed to load.
+
+        Returns:
+            bool: True if processing should continue, False if it should stop.
+        """
+        error_msg = str(error)
+
+        # Check for OAuth/authentication errors
+        if "401" in error_msg or "OAuth" in error_msg or "token" in error_msg.lower():
+            logger_gui.error(f"Authentication error: {error_msg}")
+            logger_gui.error("Your session has expired. Please restart the application and login again.")
+            self.s_statusbar_message.emit(
+                StatusbarMessage(message="Session expired - please restart and login", timeout=5000)
+            )
+            return False
+
+        logger_gui.warning(f"Failed to load album {album_id}: {error_msg}")
+        logger_gui.info(
+            "Note: Some albums may be unavailable due to region restrictions or removal from TIDAL. This is normal."
+        )
+        return True
+
+    def _queue_loaded_albums(self, albums_dict: dict[int, Album]) -> None:
+        """Prepare and add loaded albums to the download queue.
+
+        Args:
+            albums_dict (dict[int, Album]): Dictionary of successfully loaded albums.
+        """
+        logger_gui.info(f"Preparing queue items for {len(albums_dict)} albums...")
+
+        queue_items = []
+        for album in albums_dict.values():
+            queue_dl_item = self.media_to_queue_download_model(album)
+            if queue_dl_item:
+                queue_items.append((queue_dl_item, album))
+                logger_gui.debug(f"Prepared: {name_builder_artist(album)} - {album.name}")
+
+        # Add all items to queue
+        logger_gui.info(f"Adding {len(queue_items)} albums to queue...")
+        for queue_dl_item, album in queue_items:
+            self.queue_download_media(queue_dl_item)
+            logger_gui.info(f"Added: {name_builder_artist(album)} - {album.name}")
+
     def on_copy_url_share(
         self, tree_target: QtWidgets.QTreeWidget | QtWidgets.QTreeView, point: QtCore.QPoint = None
     ) -> None:

From e9070eef66622ac80c9e7a68b00aa268e669e8fa Mon Sep 17 00:00:00 2001
From: Winman486 <harpsystems@gmail.com>
Date: Tue, 21 Oct 2025 15:23:18 -0500
Subject: [PATCH 4/4] refactor: Make rate limiting configurable and move
 session validation to Tidal class

- Add api_rate_limit_batch_size and api_rate_limit_delay_sec to Settings (cfg.py)
- Move validate_session() and is_authentication_error() to Tidal class (config.py)
- Update _load_albums_with_rate_limiting() to use config values instead of hardcoded 20/3
- Update _handle_album_load_error() to use Tidal.is_authentication_error()
- Remove _validate_session() from gui.py (now uses Tidal.validate_session())
- Addresses maintainer feedback: configurable tweaking variables and proper separation of concerns
---
 tidal_dl_ng/config.py    | 20 ++++++++++++++++++++
 tidal_dl_ng/gui.py       | 33 ++++++++++++---------------------
 tidal_dl_ng/model/cfg.py |  5 +++++
 3 files changed, 37 insertions(+), 21 deletions(-)

diff --git a/tidal_dl_ng/config.py b/tidal_dl_ng/config.py
index 72b9f93..f390e4c 100644
--- a/tidal_dl_ng/config.py
+++ b/tidal_dl_ng/config.py
@@ -190,6 +190,26 @@ class Tidal(BaseConfig, metaclass=SingletonMeta):
 
         return True
 
+    def validate_session(self) -> bool:
+        """Validate that the TIDAL session is still authenticated.
+
+        Returns:
+            bool: True if session is valid, False otherwise.
+        """
+        return self.session.check_login()
+
+    def is_authentication_error(self, error: Exception) -> bool:
+        """Check if an error is related to authentication/OAuth issues.
+
+        Args:
+            error (Exception): The exception to check.
+
+        Returns:
+            bool: True if the error is authentication-related, False otherwise.
+        """
+        error_msg = str(error)
+        return "401" in error_msg or "OAuth" in error_msg or "token" in error_msg.lower()
+
 
 class HandlingApp(metaclass=SingletonMeta):
     event_abort: Event = Event()
diff --git a/tidal_dl_ng/gui.py b/tidal_dl_ng/gui.py
index 4bf0f06..74192f0 100644
--- a/tidal_dl_ng/gui.py
+++ b/tidal_dl_ng/gui.py
@@ -728,16 +728,19 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
             dict[int, Album]: Dictionary of successfully loaded full album objects.
         """
         albums_dict = {}
+        batch_size = self.settings.data.api_rate_limit_batch_size
+        delay_sec = self.settings.data.api_rate_limit_delay_sec
 
         for idx, album_id in enumerate(album_ids.keys(), start=1):
             try:
-                # Add delay every 20 albums to avoid rate limiting
-                if idx > 1 and (idx - 1) % 20 == 0:
-                    logger_gui.info(f"🛑 RATE LIMITING: Processed {idx - 1} albums, pausing for 3 seconds...")
-                    time.sleep(3)
+                # Add delay every N albums to avoid rate limiting
+                if idx > 1 and (idx - 1) % batch_size == 0:
+                    logger_gui.info(f"🛑 RATE LIMITING: Processed {idx - 1} albums, pausing for {delay_sec} seconds...")
+                    time.sleep(delay_sec)
 
                 # Check session validity before making API calls
-                if not self._validate_session():
+                if not self.tidal.validate_session():
+                    logger_gui.error("Session expired. Please restart the application and login again.")
                     return albums_dict
 
                 # Reload full album object
@@ -753,17 +756,6 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
         logger_gui.info(f"Successfully loaded {len(albums_dict)} albums.")
         return albums_dict
 
-    def _validate_session(self) -> bool:
-        """Validate that the TIDAL session is still authenticated.
-
-        Returns:
-            bool: True if session is valid, False otherwise.
-        """
-        if not self.tidal.session.check_login():
-            logger_gui.error("Session expired. Please restart the application and login again.")
-            return False
-        return True
-
     def _handle_album_load_error(self, error: Exception, album_id: int) -> bool:
         """Handle errors that occur when loading an album.
 
@@ -774,10 +766,9 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
         Returns:
             bool: True if processing should continue, False if it should stop.
         """
-        error_msg = str(error)
-
-        # Check for OAuth/authentication errors
-        if "401" in error_msg or "OAuth" in error_msg or "token" in error_msg.lower():
+        # Check for OAuth/authentication errors using Tidal class method
+        if self.tidal.is_authentication_error(error):
+            error_msg = str(error)
             logger_gui.error(f"Authentication error: {error_msg}")
             logger_gui.error("Your session has expired. Please restart the application and login again.")
             self.s_statusbar_message.emit(
@@ -785,7 +776,7 @@ class MainWindow(QtWidgets.QMainWindow, Ui_MainWindow):
             )
             return False
 
-        logger_gui.warning(f"Failed to load album {album_id}: {error_msg}")
+        logger_gui.warning(f"Failed to load album {album_id}: {error!s}")
         logger_gui.info(
             "Note: Some albums may be unavailable due to region restrictions or removal from TIDAL. This is normal."
         )
diff --git a/tidal_dl_ng/model/cfg.py b/tidal_dl_ng/model/cfg.py
index 1c87992..4101b9d 100644
--- a/tidal_dl_ng/model/cfg.py
+++ b/tidal_dl_ng/model/cfg.py
@@ -59,6 +59,9 @@ class Settings:
     filename_delimiter_artist: str = ", "
     filename_delimiter_album_artist: str = ", "
     metadata_target_upc: MetadataTargetUPC = MetadataTargetUPC.UPC
+    # Rate limiting for API calls (tweaking variables)
+    api_rate_limit_batch_size: int = 20  # Number of albums to process before applying rate limit delay
+    api_rate_limit_delay_sec: float = 3.0  # Delay in seconds between batches to avoid rate limiting
 
 
 @dataclass_json
@@ -127,6 +130,8 @@ class HelpSettings:
     metadata_target_upc: str = (
         "Select the target metadata tag ('UPC', 'BARCODE', 'EAN') where to write the UPC information to. Default: 'UPC'."
     )
+    api_rate_limit_batch_size: str = "Number of albums to process before applying rate limit delay (tweaking variable)."
+    api_rate_limit_delay_sec: str = "Delay in seconds between batches to avoid API rate limiting (tweaking variable)."
 
 
 @dataclass_json