Add recording lifecycle hooks for processors

Wire the main window to notify custom DLC processors when recording starts/stops, with a shared recording context (run dir, filename stem, and file metadata). Refactor processor lookup into a helper and only fall back to generic save() if no stop hook handles persistence.

Extend BaseProcessorSocket with recording context/save-path state, start/stop hook methods, and a stop(save=...) option. Update save() to use an explicit path or configured default path, create parent directories, and improve logging for skipped/failed saves.

Author: C-Achard

dlclivegui/gui/main_window.py

@@ -1793,6 +1793,7 @@ def _start_multi_camera_recording(self) -> None:
         if run_dir is None:
             self._show_error("Failed to start recording.")
             return
+        self._notify_processor_recording_started(run_dir)
         self.multi_camera_controller.set_recording_sink(self._rec_manager.write_frame)
         self.multi_camera_controller.set_recording_frame_do_emit(True)
 
@@ -1834,6 +1835,20 @@ def worker():
             daemon=True,
         ).start()
 
+    def _get_dlc_processor_instance(self):
+        """Return the active custom DLC processor instance, if available."""
+        processor = getattr(self._dlc, "_processor", None)
+
+        if processor is not None:
+            return processor
+
+        # Fallback: if DLCLive owns it internally.
+        dlc_obj = getattr(self._dlc, "_dlc", None)
+        if dlc_obj is not None:
+            return getattr(dlc_obj, "processor", None)
+
+        return None
+
     def _save_processor_data_if_available(self) -> None:
         """Best-effort generic processor save.
 
@@ -1845,12 +1860,7 @@ def _save_processor_data_if_available(self) -> None:
 
         Return values are only logged; failure should not crash the GUI.
         """
-        processor = getattr(self._dlc, "_processor", None)
-
-        # Fallback in case DLCLive owns the processor but _processor was not updated.
-        if processor is None:
-            dlc_obj = getattr(self._dlc, "_dlc", None)
-            processor = getattr(dlc_obj, "processor", None) if dlc_obj is not None else None
+        processor = self._get_dlc_processor_instance()
 
         if processor is None:
             logger.debug("Processor save skipped: no processor instance available.")
@@ -1867,8 +1877,82 @@ def _save_processor_data_if_available(self) -> None:
         except Exception:
             logger.exception("Processor save() failed.")
 
+    def _notify_processor_recording_started(self, run_dir) -> None:
+        processor = self._get_dlc_processor_instance()
+        if processor is None:
+            return
+
+        hook = getattr(processor, "on_recording_started", None)
+        if not callable(hook):
+            return
+
+        try:
+            context = self._build_processor_recording_context(run_dir)
+            hook(context)
+            logger.info("Notified processor recording started: %s", context)
+        except Exception:
+            logger.exception("Processor on_recording_started hook failed")
+
+    from pathlib import Path
+
+    def _build_processor_recording_context(self, run_dir) -> dict:
+        run_dir = Path(run_dir) if run_dir is not None else None
+
+        file_context = {}
+        try:
+            file_context = self._rec_manager.get_recording_file_context()
+        except Exception:
+            logger.exception("Failed to get recording file context from RecordingManager")
+            file_context = {}
+
+        if run_dir is None:
+            run_dir = file_context.get("run_dir", None)
+        if run_dir is not None:
+            run_dir = Path(run_dir)
+
+        session_name = ""
+        if hasattr(self, "session_name_edit"):
+            session_name = self.session_name_edit.text().strip()
+
+        filename = ""
+        if hasattr(self, "filename_edit"):
+            filename = self.filename_edit.text().strip()
+
+        filename_stem = Path(filename or session_name or "recording").stem
+
+        ctx = {
+            "run_dir": run_dir,
+            "session_name": session_name,
+            "filename": filename,
+            "filename_stem": filename_stem,
+            "processor_base_path": run_dir / filename_stem if run_dir is not None else None,
+        }
+        ctx.update(file_context)
+        return ctx
+
+    def _notify_processor_recording_stopped(self) -> None:
+        processor = self._get_dlc_processor_instance()
+        if processor is None:
+            return False
+
+        hook = getattr(processor, "on_recording_stopped", None)
+        if not callable(hook):
+            return False
+
+        try:
+            run_dir = getattr(self._rec_manager, "run_dir", None)
+            context = self._build_processor_recording_context(run_dir)
+            hook(context)
+            logger.info("Notified processor recording stopped")
+            return True
+        except Exception:
+            logger.exception("Processor on_recording_stopped hook failed")
+            return False
+
     def _on_recording_stopped_async(self) -> None:
-        self._save_processor_data_if_available()
+        handled_by_stop_hook = self._notify_processor_recording_stopped()
+        if not handled_by_stop_hook:
+            self._save_processor_data_if_available()
 
         self._recording_stopping = False
         self.start_record_button.setEnabled(True)

dlclivegui/processors/dlc_processor_socket.py

@@ -86,6 +86,8 @@ def __init__(
         self._vid_recording = Event()
         self.curr_step = 0
         self.save_original = save_original
+        self.recording_context = {}
+        self.save_path = None
 
         # Networking (optional)
         self.address = bind
@@ -265,8 +267,14 @@ def stop_recording(self):
     # STOP / SHUTDOWN
     # --------------------------------------------------------------------------------------
 
-    def stop(self):
+    def stop(self, save: bool = False, file=None):
         """Gracefully stop listener and clients."""
+        if save:
+            try:
+                self.save(file)
+            except Exception:
+                logger.exception("Failed to save processor data on stop")
+
         if self._stop.is_set():
             return
 
@@ -370,23 +378,79 @@ def _clear_data_queues(self):
             self.original_pose.clear()
 
     def save(self, file=None):
-        if not file:
+        target = file
+
+        if target is None:
+            target = getattr(self, "save_path", None)
+
+        if target is None:
+            logger.warning("Processor save skipped: no file or save_path provided.")
             return 0
+
         try:
             save_dict = self.get_data()
-            path2save = Path(__file__).parent.parent.parent / "data" / file
-            path2save.parent.mkdir(parents=True, exist_ok=True)
+            save_path = Path(target)
+            save_path.parent.mkdir(parents=True, exist_ok=True)
+
             if self.save_original:
                 original_pose = save_dict.pop("original_pose")
-                self.save_original_pose(original_pose, save_dict["frame_time"], save_dict["time_stamp"], path2save)
-            with open(path2save, "wb") as f:
+                self.save_original_pose(
+                    original_pose,
+                    save_dict["frame_time"],
+                    save_dict["time_stamp"],
+                    save_path,
+                )
+
+            with open(save_path, "wb") as f:
                 pickle.dump(save_dict, f)
-            logger.info(f"Saved data to {path2save}")
+
+            logger.info(f"Saved processor data to {save_path}")
             return 1
+
         except Exception as e:
             logger.error(f"Save failed: {e}")
             return -1
 
+    def set_recording_context(self, context: dict | None) -> None:
+        """Set GUI-provided recording context.
+
+        This is intentionally generic. Custom processors may use it to derive
+        processor-specific output paths.
+
+        Expected keys may include:
+            run_dir
+            session_name
+            filename
+            filename_stem
+            processor_base_path
+            video_files
+            timestamp_files
+        """
+        self.recording_context = dict(context or {})
+
+        base_path = self.recording_context.get("processor_base_path")
+        if base_path is not None:
+            self.save_path = Path(base_path)
+
+    def set_save_path(self, path) -> None:
+        """Set default save path used by save() when no file is provided."""
+        self.save_path = Path(path) if path is not None else None
+
+    def get_save_path(self):
+        """Return default save path, if any."""
+        return getattr(self, "save_path", None)
+
+    def on_recording_started(self, context: dict) -> None:
+        """Optional hook called by GUI when recording starts."""
+        self.set_recording_context(context)
+
+    def on_recording_stopped(self, context: dict) -> None:
+        """Optional hook called by GUI when recording stops.
+
+        Base implementation only updates context. Custom processors can override.
+        """
+        self.set_recording_context(context)
+
     def save_original_pose(
         self,
         original_pose: np.ndarray,