PICARD-3118: Allow user to save/load current Picard session

picard/album.py

@@ -538,6 +538,8 @@ def _load_track(node, mm, artists, extra_metadata):
             track.metadata['~totalalbumtracks'] = totalalbumtracks
             if multiartists:
                 track.metadata['~multiartist'] = '1'
+        # Preserve release JSON for session export after load finished
+        self._release_node_cache = self._release_node
         del self._release_node
         del self._release_artist_nodes
         self._tracks_loaded = True

picard/options.py

@@ -69,6 +69,7 @@
     DEFAULT_WIN_COMPAT_REPLACEMENTS,
 )
 from picard.i18n import N_
+from picard.session.constants import SessionMessages
 
 from picard.ui.colors import InterfaceColors
 
@@ -146,6 +147,8 @@
 Option('persist', 'window_state', QtCore.QByteArray())
 ListOption('persist', 'filters_FileTreeView', None)
 ListOption('persist', 'filters_AlbumTreeView', None)
+TextOption('persist', 'last_session_path', '')
+TextOption('persist', 'session_autosave_path', '')
 
 # picard/ui/metadatabox.py
 #
@@ -491,6 +494,39 @@ def make_default_toolbar_layout():
 Option('setting', 'file_renaming_scripts', {})
 TextOption('setting', 'selected_file_naming_script_id', '', title=N_("Selected file naming script"))
 
+# picard/ui/options/sessions.py
+# Sessions
+BoolOption(
+    'setting',
+    'session_safe_restore',
+    True,
+    title=N_(SessionMessages.SESSION_SAFE_RESTORE_TITLE),
+)
+BoolOption(
+    'setting',
+    'session_load_last_on_startup',
+    False,
+    title=N_(SessionMessages.SESSION_LOAD_LAST_TITLE),
+)
+IntOption(
+    'setting',
+    'session_autosave_interval_min',
+    0,
+    title=N_(SessionMessages.SESSION_AUTOSAVE_TITLE),
+)
+BoolOption(
+    'setting',
+    'session_backup_on_crash',
+    True,
+    title=N_(SessionMessages.SESSION_BACKUP_TITLE),
+)
+BoolOption(
+    'setting',
+    'session_include_mb_data',
+    False,
+    title=N_(SessionMessages.SESSION_INCLUDE_MB_DATA_TITLE),
+)
+
 # picard/ui/searchdialog/album.py
 #
 Option('persist', 'albumsearchdialog_header_state', QtCore.QByteArray())

picard/session/__init__.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+#
+# Picard, the next-generation MusicBrainz tagger
+#
+# Copyright (C) 2025 The MusicBrainz Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+"""Session management package for Picard."""

picard/session/constants.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+#
+# Picard, the next-generation MusicBrainz tagger
+#
+# Copyright (C) 2025 The MusicBrainz Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+"""Constants for session management.
+
+This module contains all constants used throughout the session management system,
+including retry delays, file extensions, and excluded tags.
+"""
+
+
+class SessionConstants:
+    """Constants for session management operations."""
+
+    # File handling
+    SESSION_FILE_EXTENSION = ".mbps.gz"
+    SESSION_FORMAT_VERSION = 1
+
+    # Retry delays in milliseconds
+    DEFAULT_RETRY_DELAY_MS = 200
+    FAST_RETRY_DELAY_MS = 150
+
+    # Metadata handling
+    INTERNAL_TAG_PREFIX = "~"
+    EXCLUDED_OVERRIDE_TAGS = frozenset({"length", "~length"})
+
+    # Location types
+    LOCATION_UNCLUSTERED = "unclustered"
+    LOCATION_TRACK = "track"
+    LOCATION_ALBUM_UNMATCHED = "album_unmatched"
+    LOCATION_CLUSTER = "cluster"
+    LOCATION_NAT = "nat"
+
+
+class SessionMessages:
+    """Centralized session-related message strings.
+
+    Define raw, untranslated strings. Call sites should mark for translation:
+    - API/config titles: wrap with N_()
+    - UI labels: wrap with _()
+    """
+
+    # Option titles (API/config)
+    SESSION_SAFE_RESTORE_TITLE = "Honor local edits and placement on load (no auto-matching)"
+    SESSION_LOAD_LAST_TITLE = "Load last saved session on startup"
+    SESSION_AUTOSAVE_TITLE = "Auto-save session every N minutes (0 disables)"
+    SESSION_BACKUP_TITLE = "Attempt to keep a session backup on unexpected shutdown"
+    SESSION_INCLUDE_MB_DATA_TITLE = "Include MusicBrainz data in saved sessions (faster loads, risk of stale data)"

picard/session/location_detector.py

@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+#
+# Picard, the next-generation MusicBrainz tagger
+#
+# Copyright (C) 2025 The MusicBrainz Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+"""Location detection for session management.
+
+This module handles detecting where files should be placed within a session,
+separating the complex location detection logic from other concerns.
+"""
+
+from __future__ import annotations
+
+from picard.album import Album, NatAlbum
+from picard.cluster import Cluster, UnclusteredFiles
+from picard.file import File
+from picard.session.constants import SessionConstants
+from picard.session.session_data import SessionItemLocation
+from picard.track import Track
+
+
+class LocationDetector:
+    """Detects the location type of files in the session."""
+
+    def detect(self, file: File) -> SessionItemLocation:
+        """Detect where a file should be placed in the session.
+
+        Parameters
+        ----------
+        file : File
+            The file to detect the location for.
+
+        Returns
+        -------
+        SessionItemLocation
+            The location information for the file.
+
+        Notes
+        -----
+        This method analyzes the file's parent item to determine its proper
+        location within the session structure.
+        """
+        parent = file.parent_item
+        if parent is None:
+            return self._unclustered_location()
+
+        if self._is_track_parent(parent):
+            return self._detect_track_location(parent)
+        elif self._is_cluster_parent(parent):
+            return self._detect_cluster_location(parent)
+        else:
+            return self._unclustered_location()
+
+    def _is_track_parent(self, parent: object) -> bool:
+        """Check if parent is a track (has album attribute).
+
+        Parameters
+        ----------
+        parent : object
+            The parent item to check.
+
+        Returns
+        -------
+        bool
+            True if parent is a track.
+        """
+        return hasattr(parent, 'album') and isinstance(parent.album, Album)
+
+    def _is_cluster_parent(self, parent: object) -> bool:
+        """Check if parent is a cluster.
+
+        Parameters
+        ----------
+        parent : object
+            The parent item to check.
+
+        Returns
+        -------
+        bool
+            True if parent is a cluster.
+        """
+        return isinstance(parent, Cluster)
+
+    def _detect_track_location(self, parent: Track) -> SessionItemLocation:
+        """Detect location for files under a track.
+
+        Parameters
+        ----------
+        parent : Track
+            The track parent item.
+
+        Returns
+        -------
+        SessionItemLocation
+            The location information for the track.
+        """
+        if isinstance(parent.album, NatAlbum):
+            # NAT special handling
+            return SessionItemLocation(type=SessionConstants.LOCATION_NAT, recording_id=parent.id)
+
+        # Track placement
+        if hasattr(parent, 'id') and parent.id:
+            return SessionItemLocation(
+                type=SessionConstants.LOCATION_TRACK, album_id=parent.album.id, recording_id=parent.id
+            )
+
+        # Fallback to album unmatched
+        return SessionItemLocation(type=SessionConstants.LOCATION_ALBUM_UNMATCHED, album_id=parent.album.id)
+
+    def _detect_cluster_location(self, parent: Cluster) -> SessionItemLocation:
+        """Detect location for files under a cluster.
+
+        Parameters
+        ----------
+        parent : Cluster
+            The cluster parent item.
+
+        Returns
+        -------
+        SessionItemLocation
+            The location information for the cluster.
+        """
+        # Unmatched files inside an album
+        if parent.related_album:
+            return SessionItemLocation(type=SessionConstants.LOCATION_ALBUM_UNMATCHED, album_id=parent.related_album.id)
+
+        # Left pane cluster
+        if isinstance(parent, UnclusteredFiles):
+            return self._unclustered_location()
+
+        return SessionItemLocation(
+            type=SessionConstants.LOCATION_CLUSTER,
+            cluster_title=str(parent.metadata['album']),
+            cluster_artist=str(parent.metadata['albumartist']),
+        )
+
+    def _unclustered_location(self) -> SessionItemLocation:
+        """Create an unclustered location.
+
+        Returns
+        -------
+        SessionItemLocation
+            Location for unclustered files.
+        """
+        return SessionItemLocation(type=SessionConstants.LOCATION_UNCLUSTERED)