main_window.py

"""PySide6 based GUI for DeepLabCut Live."""

from __future__ import annotations

import importlib.metadata
import json
import logging
import os
import threading
import time
from pathlib import Path

import cv2
import numpy as np
from PySide6.QtCore import QRect, QSettings, Qt, QTimer, QUrl, Signal
from PySide6.QtGui import (
    QAction,
    QActionGroup,
    QCloseEvent,
    QColor,
    QDesktopServices,
    QFont,
    QIcon,
    QImage,
    QPainter,
    QPixmap,
)
from PySide6.QtWidgets import (
    QCheckBox,
    QComboBox,
    QDockWidget,
    QFileDialog,
    QFormLayout,
    QGridLayout,
    QGroupBox,
    QHBoxLayout,
    QLabel,
    QLineEdit,
    QMainWindow,
    QMessageBox,
    QPushButton,
    QSizePolicy,
    QSpinBox,
    QStatusBar,
    QStyle,
    QVBoxLayout,
    QWidget,
)

from dlclivegui.cameras import CameraFactory
from dlclivegui.config import (
    ALLOWED_VIDEO_CONTAINERS,
    DEFAULT_CONFIG,
    DEFAULT_RECORDING_CONTAINER,
    DLC_DO_LOG_TIMING,
    GUI_MAX_DISPLAY_FPS,
    RECORD_STOP_RETRY_INTERVAL,
    RECORD_STOP_RETRY_TIMEOUT,
    ApplicationSettings,
    BoundingBoxSettings,
    CameraSettings,
    DLCProcessorSettings,
    MultiCameraSettings,
    RecordingSettings,
    VisualizationSettings,
)

from ..processors.processor_utils import (
    create_spec_from_scan,
    default_processors_dir,
    instantiate_from_scan,
    log_processor_context,
    processor_builds_in_worker,
    scan_processor_folder,
    scan_processor_package,
)
from ..services.dlc_processor import DLCLiveProcessor, PoseResult
from ..services.multi_camera_controller import MultiCameraController, MultiFrameData, get_camera_id, get_display_id
from ..services.recording_manager import RecordingManager
from ..utils.display import BBoxColors, compute_tile_info, create_tiled_frame, draw_bbox, draw_pose
from ..utils.settings_store import DLCLiveGUISettingsStore, ModelPathStore
from ..utils.stats import WorkerTimingStats, format_dlc_stats
from ..utils.utils import FPSTracker
from .camera_config.camera_config_dialog import CameraConfigDialog
from .misc import color_dropdowns as color_ui
from .misc import layouts as lyts
from .misc.drag_spinbox import ScrubSpinBox
from .misc.eliding_label import ElidingPathLabel
from .theme import LOGO, LOGO_ALPHA, AppStyle, apply_theme

logger = logging.getLogger("DLCLiveGUI")


class DLCLiveMainWindow(QMainWindow):
    """Main application window."""

    _recording_stopped_async = Signal()
    _rec_stop_failed_async = Signal(str)

    def __init__(self, config: ApplicationSettings | None = None):
        super().__init__()
        self.setWindowTitle("DeepLabCut Live GUI")

        self.settings = QSettings("DeepLabCut", "DLCLiveGUI")
        self._model_path_store: ModelPathStore = ModelPathStore(self.settings)
        self._settings_store: DLCLiveGUISettingsStore = DLCLiveGUISettingsStore(self.settings)

        last_cfg_path = self._settings_store.get_last_config_path()
        last_cfg_file = self._valid_config_file_path(last_cfg_path)
        if config is None:
            # 1) snapshot
            cfg = self._settings_store.load_full_config_snapshot()
            if cfg is not None:
                config = cfg
                self._config_path = last_cfg_file
                if self._config_path is not None:
                    logger.info(f"Loaded configuration from QSettings snapshot; associated file: {self._config_path}")
                else:
                    logger.info("Loaded configuration from QSettings snapshot without associated config file.")

            else:
                # 2) last config file path
                if last_cfg_file is not None:
                    try:
                        config = ApplicationSettings.load(str(last_cfg_file))
                        self._config_path = last_cfg_file
                        logger.info(f"Loaded configuration from last config file: {last_cfg_file}")
                    except Exception as exc:
                        logger.warning(
                            f"Failed to load last config file ({last_cfg_file}): {exc}. Using default config."
                        )
                        config = DEFAULT_CONFIG
                        self._config_path = None
                else:
                    # 3) default
                    config = DEFAULT_CONFIG
                    self._config_path = None
        else:
            self._config_path = None

        self._fps_tracker = FPSTracker()
        self._rec_manager = RecordingManager()
        self._dlc = DLCLiveProcessor()
        self.multi_camera_controller = MultiCameraController()
        ### Time debug
        self._dlc_timing = WorkerTimingStats(
            "GUI - DLC Worker", logger=logger, log_interval=2.0, enabled=DLC_DO_LOG_TIMING
        )

        self._config = config
        self._inference_camera_id: str | None = self._settings_store.get_inference_camera_id()
        self._active_inference_camera_id: str | None = None
        self._running_cams_ids: set[str] = set()
        self._current_frame: np.ndarray | None = None
        self._raw_frame: np.ndarray | None = None
        self._last_pose: PoseResult | None = None
        self._dlc_active: bool = False
        self._processor_recording_context: dict | None = None
        self._processor_recording_started_notified = False
        self._pending_recording_after_preview = False
        self._active_camera_settings: CameraSettings | None = None
        self._last_drop_warning = 0.0
        self._last_recorder_summary = "Recorder idle"
        self._display_interval = 1.0 / 25.0
        self._last_display_time = 0.0
        self._dlc_initialized = False
        self._scanned_processors: dict = {}
        self._processor_keys: list = []
        self._last_processor_vid_recording = False
        self._auto_record_session_name: str | None = None
        self._bbox_x0 = 0
        self._bbox_y0 = 0
        self._bbox_x1 = 0
        self._bbox_y1 = 0
        self._bbox_enabled = False
        # UI elements
        self._current_style: AppStyle = AppStyle.DARK
        self._cam_dialog: CameraConfigDialog | None = None

        # Visualization settings (will be updated from config)
        self._p_cutoff = 0.6
        self._colormap = "hot"
        self._bbox_color = (0, 0, 255)  # BGR: red

        # Multi-camera state
        self._multi_camera_mode = False
        self._multi_camera_frames: dict[str, np.ndarray] = {}
        self._multi_camera_display_ids: dict[str, str] = {}  # camera_id -> display_id (for labeling)
        # DLC pose rendering info for tiled view
        self._dlc_tile_offset: tuple[int, int] = (0, 0)  # (x, y) offset in tiled frame
        self._dlc_tile_scale: tuple[float, float] = (1.0, 1.0)  # (scale_x, scale_y)
        # Display flag (decoupled from frame capture for performance)
        self._display_dirty: bool = False
        # Recording state
        self._recording_stopping = False
        self._recording_stopped_async.connect(self._on_recording_stopped_async)
        self._rec_stop_failed_async.connect(self._on_recording_stop_failed_async)

        self._load_icons()
        self._preview_pixmap = QPixmap(LOGO_ALPHA)
        self._setup_ui()
        self._connect_signals()
        self._apply_config(self._config, restore_local_prefs=True)
        self._refresh_processors()  # Scan and populate processor dropdown
        self._update_inference_buttons()
        self._update_camera_controls_enabled()
        self._metrics_timer = QTimer(self)
        self._metrics_timer.setInterval(500)
        self._metrics_timer.timeout.connect(self._update_metrics)
        self._metrics_timer.start()
        self._update_metrics()

        # Display timer - decoupled from frame capture for performance
        self._display_timer = QTimer(self)
        self._display_timer.setInterval(1000 / GUI_MAX_DISPLAY_FPS)  # in ms, ~30 fps display rate
        self._display_timer.timeout.connect(self._update_display_from_pending)
        self._display_timer.start()

        # Validate cameras from loaded config (deferred to allow window to show first)
        # NOTE IMPORTANT (tests/CI): This is scheduled via a QTimer and may fire during pytest-qt teardown.
        # NOTE @C-Achard 2026-03-02: Handling this in closeEvent should help
        self._camera_validation_timer = QTimer(self)
        self._camera_validation_timer.setSingleShot(True)
        self._camera_validation_timer.timeout.connect(self._validate_configured_cameras)
        self._camera_validation_timer.start(100)
        # If validation triggers a modal QMessageBox (warning/error) while the parent window is closing,
        # it can cause errors with unpredictable timing (heap corruption / access violations).
        #
        # Mitigations for tests/CI:
        #   - Disable this timer by monkeypatching _validate_configured_cameras in GUI tests
        #   - OR monkeypatch/override _show_warning/_show_error to no-op in GUI tests (easiest)

    def resizeEvent(self, event):
        super().resizeEvent(event)
        if not self.multi_camera_controller.is_running():
            self._show_logo_and_text()

    def _valid_config_file_path(self, path: str | None) -> Path | None:
        if not path:
            return None

        try:
            p = Path(path).expanduser()
            if p.exists() and p.is_file():
                return p.resolve()
        except Exception:
            logger.debug("Invalid config file path: %s", path, exc_info=True)

        return None

    # ------------------------------------------------------------------ UI
    def _init_theme_actions(self) -> None:
        """Set initial checked state for theme actions based on current app stylesheet."""
        self.action_dark_mode.setChecked(self._current_style == AppStyle.DARK)
        self.action_light_mode.setChecked(self._current_style == AppStyle.SYS_DEFAULT)

    def _apply_theme(self, mode: AppStyle) -> None:
        """Apply the selected theme and update menu action states."""
        apply_theme(mode, self.action_dark_mode, self.action_light_mode)
        self._current_style = mode

    def _load_icons(self):
        self.setWindowIcon(QIcon(LOGO))

    def _setup_ui(self) -> None:
        # central = QWidget()
        # layout = QHBoxLayout(central)

        # Video panel with display and performance stats
        video_panel = QWidget()
        video_layout = QVBoxLayout(video_panel)
        video_layout.setContentsMargins(0, 0, 0, 0)
        ## Video display widget
        self.video_label = QLabel()
        self.video_label.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.video_label.setMinimumSize(640, 360)
        self.video_label.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)
        video_layout.addWidget(self.video_label, stretch=1)
        ## Stats panel below video with clear labels
        stats_widget = QWidget()
        stats_widget.setStyleSheet("padding: 5px;")
        # stats_widget.setMinimumWidth(800)  # Prevent excessive line breaks
        stats_widget.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Fixed)
        stats_widget.setMinimumHeight(80)
        self._build_stats_layout(stats_widget)

        video_layout.addWidget(stats_widget, stretch=0)

        # Central widget is just the video panel (video + stats)
        video_panel.setLayout(video_layout)
        self.setCentralWidget(video_panel)

        # Allow user to select stats text
        for lbl in (self.camera_stats_label, self.dlc_stats_label, self.recording_stats_label):
            lbl.setTextInteractionFlags(Qt.TextSelectableByMouse)

        # Controls panel content
        controls_content_widget = QWidget()
        controls_content_widget.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)

        controls_layout = QVBoxLayout(controls_content_widget)
        controls_layout.setContentsMargins(5, 5, 5, 0)
        controls_layout.addWidget(self._build_camera_group())
        controls_layout.addWidget(self._build_dlc_group())
        controls_layout.addWidget(self._build_recording_group())
        controls_layout.addWidget(self._build_viz_group())

        # Preview/Stop buttons stay outside the scroll area as a fixed footer
        button_bar_widget = QWidget()
        button_bar_widget.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Fixed)

        button_bar = QHBoxLayout(button_bar_widget)
        button_bar.setContentsMargins(0, 5, 0, 5)

        self.preview_button = QPushButton("Start Preview")
        self.preview_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_MediaPlay))
        self.preview_button.setMinimumWidth(150)

        self.stop_preview_button = QPushButton("Stop Preview")
        self.stop_preview_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_MediaStop))
        self.stop_preview_button.setEnabled(False)
        self.stop_preview_button.setMinimumWidth(150)

        button_bar.addWidget(self.preview_button)
        button_bar.addWidget(self.stop_preview_button)

        controls_widget = lyts.make_scrollable_with_fixed_footer(
            controls_content_widget,
            button_bar_widget,
            object_name="ControlsPanel",
            scroll_object_name="ControlsScrollArea",
            footer_object_name="ControlsFooter",
            margins=(0, 0, 0, 0),
            spacing=0,
            footer_margins=(5, 0, 5, 0),
        )

        # Add controls and video panel to main layout
        ## Dock widget for controls
        self.controls_dock = QDockWidget("Controls", self)
        self.controls_dock.setObjectName("ControlsDock")  # important for state saving
        self.controls_dock.setWidget(controls_widget)
        ### Dock features
        self.controls_dock.setFeatures(
            # must not be closable by user but visibility can be toggled from View -> Show controls
            QDockWidget.DockWidgetMovable | QDockWidget.DockWidgetFloatable  # | QDockWidget.DockWidgetClosable
        )
        self.addDockWidget(Qt.LeftDockWidgetArea, self.controls_dock)
        self.setDockOptions(
            self.dockOptions()
            | QMainWindow.DockOption.AllowTabbedDocks
            | QMainWindow.DockOption.GroupedDragging
            | QMainWindow.DockOption.AnimatedDocks
        )
        self.controls_dock.setStyleSheet(
            """/* Docked title bar: fully transparent */
            QDockWidget#ControlsDock::title {
                background-color: rgba(0, 0, 0, 0);
            }
            """
        )

        self.setStatusBar(QStatusBar())
        self._build_menus()
        QTimer.singleShot(0, self._show_logo_and_text)

    def _build_stats_layout(self, stats_widget: QWidget) -> QGridLayout:
        stats_layout = QGridLayout(stats_widget)
        stats_layout.setContentsMargins(5, 5, 5, 5)
        stats_layout.setHorizontalSpacing(8)  # tighten horizontal gap between title and value
        stats_layout.setVerticalSpacing(3)

        row = 0

        # Camera
        title_camera = QLabel("<b>Camera:</b>")
        title_camera.setSizePolicy(QSizePolicy.Minimum, QSizePolicy.Preferred)
        stats_layout.addWidget(title_camera, row, 0, alignment=Qt.AlignTop)

        self.camera_stats_label = QLabel("Camera idle")
        self.camera_stats_label.setWordWrap(True)
        self.camera_stats_label.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Preferred)
        stats_layout.addWidget(self.camera_stats_label, row, 1, alignment=Qt.AlignTop)
        row += 1

        # DLC
        title_dlc = QLabel("<b>DLC Processor:</b>")
        title_dlc.setSizePolicy(QSizePolicy.Minimum, QSizePolicy.Preferred)
        stats_layout.addWidget(title_dlc, row, 0, alignment=Qt.AlignTop)

        self.dlc_stats_label = QLabel("DLC processor idle")
        self.dlc_stats_label.setWordWrap(True)
        self.dlc_stats_label.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Preferred)
        stats_layout.addWidget(self.dlc_stats_label, row, 1, alignment=Qt.AlignTop)
        row += 1

        # Recorder
        title_rec = QLabel("<b>Recorder:</b>")
        title_rec.setSizePolicy(QSizePolicy.Minimum, QSizePolicy.Preferred)
        stats_layout.addWidget(title_rec, row, 0, alignment=Qt.AlignTop)

        self.recording_stats_label = QLabel("Recorder idle")
        self.recording_stats_label.setWordWrap(True)
        self.recording_stats_label.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Preferred)
        stats_layout.addWidget(self.recording_stats_label, row, 1, alignment=Qt.AlignTop)

        # Critical: make column 1 (values) eat the width, keep column 0 tight
        stats_layout.setColumnStretch(0, 0)
        stats_layout.setColumnStretch(1, 1)

        stats_widget.setLayout(stats_layout)

    def _build_menus(self) -> None:
        # File menu
        file_menu = self.menuBar().addMenu("&File")

        ## Save/Load config
        self.load_config_action = QAction("Load configuration…", self)
        self.load_config_action.triggered.connect(self._action_load_config)
        file_menu.addAction(self.load_config_action)
        save_action = QAction("Save configuration", self)
        save_action.triggered.connect(self._action_save_config)
        file_menu.addAction(save_action)
        save_as_action = QAction("Save configuration as…", self)
        save_as_action.triggered.connect(self._action_save_config_as)
        file_menu.addAction(save_as_action)
        ## Open recording folder
        open_rec_folder_action = QAction("Open recording folder", self)
        open_rec_folder_action.triggered.connect(self._action_open_recording_folder)
        file_menu.addAction(open_rec_folder_action)
        ## Close
        file_menu.addSeparator()
        exit_action = QAction("Close window", self)
        exit_action.triggered.connect(self.close)
        file_menu.addAction(exit_action)

        # View menu
        view_menu = self.menuBar().addMenu("&View")
        ## Show/hide controls dock
        self.action_show_controls = QAction("Show controls", self, checkable=True)
        self.action_show_controls.setChecked(True)
        self.action_show_controls.toggled.connect(self.controls_dock.setVisible)
        self.controls_dock.visibilityChanged.connect(self.action_show_controls.setChecked)
        view_menu.addAction(self.action_show_controls)
        ## --------------------
        view_menu.addSeparator()
        ## Style actions
        appearance_menu = view_menu.addMenu("Appearance")
        self.action_dark_mode = QAction("Dark theme", self, checkable=True)
        self.action_light_mode = QAction("System theme", self, checkable=True)
        theme_group = QActionGroup(self)
        theme_group.setExclusive(True)
        theme_group.addAction(self.action_dark_mode)
        theme_group.addAction(self.action_light_mode)
        self.action_dark_mode.triggered.connect(lambda: self._apply_theme(AppStyle.DARK))
        self.action_light_mode.triggered.connect(lambda: self._apply_theme(AppStyle.SYS_DEFAULT))
        # ----------------------
        appearance_menu.addAction(self.action_light_mode)
        appearance_menu.addAction(self.action_dark_mode)
        self._apply_theme(self._current_style)
        self._init_theme_actions()

        # Help menu
        help_menu = self.menuBar().addMenu("&Help")

        view_docs_action = QAction("View documentation", self)
        view_docs_action.triggered.connect(self._action_view_documentation)
        help_menu.addAction(view_docs_action)

    def _build_camera_group(self) -> QGroupBox:
        group = QGroupBox("Camera")
        form = QFormLayout(group)

        # Camera config button - opens dialog for all camera configuration
        config_layout = QHBoxLayout()
        self.config_cameras_button = QPushButton("Configure Cameras...")
        self.config_cameras_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_ComputerIcon))
        self.config_cameras_button.setToolTip("Configure camera settings (single or multi-camera)")
        config_layout.addWidget(self.config_cameras_button)
        form.addRow(config_layout)

        # Active cameras display label
        self.active_cameras_label = QLabel("No cameras configured")
        self.active_cameras_label.setWordWrap(True)
        form.addRow("Active:", self.active_cameras_label)

        return group

    def _build_dlc_group(self) -> QGroupBox:
        group = QGroupBox("DLCLive")
        form = QFormLayout(group)

        path_layout = QHBoxLayout()
        self.model_path_edit = QLineEdit()
        self.model_path_edit.setPlaceholderText("/path/to/exported/model")
        path_layout.addWidget(self.model_path_edit)
        self.browse_model_button = QPushButton("Browse…")
        self.browse_model_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_DirOpenIcon))
        self.browse_model_button.clicked.connect(self._action_browse_model)
        path_layout.addWidget(self.browse_model_button)
        form.addRow("Model file", path_layout)

        # Processor selection
        processor_path_layout = QHBoxLayout()
        self.processor_folder_edit = QLineEdit()
        self.processor_folder_edit.setText(self._settings_store.get_processor_folder(default=default_processors_dir()))
        processor_path_layout.addWidget(self.processor_folder_edit)

        self.browse_processor_folder_button = QPushButton("Browse...")
        self.browse_processor_folder_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_DirOpenIcon))
        self.browse_processor_folder_button.clicked.connect(self._action_browse_processor_folder)
        self.browse_processor_folder_button.setToolTip(
            "Select the folder to scan for DLC processor plugins."
            "<br>Plugins must inherit from dlclive.Processor, see dlclivegui.processors for more details."
            "<br><b>Important:</b> External processors are Python code that will be imported during discovery."
            "<br>Only use processor plugins from trusted sources to avoid security risks."
        )
        processor_path_layout.addWidget(self.browse_processor_folder_button)

        self.refresh_processors_button = QPushButton("Refresh")
        self.refresh_processors_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_BrowserReload))
        self.refresh_processors_button.clicked.connect(self._refresh_processors)
        processor_path_layout.addWidget(self.refresh_processors_button)
        form.addRow("Processor folder", processor_path_layout)

        self.processor_combo = color_ui.ShrinkCurrentWidePopupComboBox(sizing=color_ui.ComboSizing(max_width=100))
        self.processor_combo.addItem("No Processor", None)
        # form.addRow("Processor", self.processor_combo)

        # self.additional_options_edit = QPlainTextEdit()
        # self.additional_options_edit.setPlaceholderText("")
        # self.additional_options_edit.setFixedHeight(40)
        # form.addRow("Additional options", self.additional_options_edit)
        self.dlc_camera_combo = color_ui.ShrinkCurrentWidePopupComboBox(sizing=color_ui.ComboSizing(max_width=180))
        self.dlc_camera_combo.setToolTip("Select which camera to use for pose inference")
        # form.addRow("Inference camera", self.dlc_camera_combo)
        self.dlc_camera_combo.setPlaceholderText("None")
        processing_sttgs = lyts.make_two_field_row(
            "Inference camera",
            self.dlc_camera_combo,
            "Custom processor",
            self.processor_combo,
            key_width=None,
        )
        self.dlc_camera_combo.update_shrink_width()
        form.addRow(processing_sttgs)

        self.processor_status_label = QLabel("Processor: No clients | Recording: No")
        self.processor_status_label.setWordWrap(True)
        # form.addRow("Processor Status", self.processor_status_label)
        self.use_custom_proc_checkbox = QCheckBox("Use custom processor")
        self.use_custom_proc_checkbox.setChecked(False)
        self.use_custom_proc_checkbox.setToolTip(
            "If enabled, the GUI will load and interact with the selected processor plugin.\n"
        )
        self.processor_toggle_row = lyts.make_two_field_row(
            "Processor status",
            self.processor_status_label,
            None,
            self.use_custom_proc_checkbox,
            key_width=None,
            left_stretch=0,
            right_stretch=0,
            style_values=False,
        )
        self.processor_toggle_row.setVisible(False)  # Hide until a processor is selected
        form.addRow(self.processor_toggle_row)

        # Wrap inference buttons in a widget to prevent shifting
        inference_button_widget = QWidget()
        inference_buttons = QHBoxLayout(inference_button_widget)
        inference_buttons.setContentsMargins(0, 0, 0, 0)
        self.start_inference_button = QPushButton("Start pose inference")
        self.start_inference_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_ArrowRight))
        self.start_inference_button.setEnabled(False)
        self.start_inference_button.setMinimumWidth(150)
        inference_buttons.addWidget(self.start_inference_button)
        self.stop_inference_button = QPushButton("Stop pose inference")
        self.stop_inference_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_BrowserStop))
        self.stop_inference_button.setEnabled(False)
        self.stop_inference_button.setMinimumWidth(150)
        inference_buttons.addWidget(self.stop_inference_button)
        form.addRow(inference_button_widget)

        # self.show_predictions_checkbox = QCheckBox("Display pose predictions")
        # self.show_predictions_checkbox.setChecked(True)
        # form.addRow(self.show_predictions_checkbox)

        return group

    def _build_recording_group(self) -> QGroupBox:
        """Build recording controls group."""
        group = QGroupBox("Recording")
        form = QFormLayout(group)
        # Output directory selection
        dir_layout = QHBoxLayout()
        self.output_directory_edit = QLineEdit()
        dir_layout.addWidget(self.output_directory_edit)
        browse_dir = QPushButton("Browse…")
        browse_dir.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_DirOpenIcon))
        browse_dir.clicked.connect(self._action_browse_directory)
        dir_layout.addWidget(browse_dir)
        form.addRow("Output directory", dir_layout)

        # Session + run name
        self.session_name_edit = QLineEdit()
        self.session_name_edit.setPlaceholderText("e.g. mouseA_day1")
        # form.addRow("Session name", self.session_name_edit)

        self.use_timestamp_checkbox = QCheckBox("Use timestamp for run folder name")
        self.use_timestamp_checkbox.setChecked(True)
        self.use_timestamp_checkbox.setToolTip(
            "If checked, run folder will be run_YYYYMMDD_HHMMSS_mmm.\n"
            "If unchecked, run folder will be run_0001, run_0002, ..."
        )
        # form.addRow("", self.use_timestamp_checkbox)
        session_opts = lyts.make_two_field_row(
            "Session name", self.session_name_edit, None, self.use_timestamp_checkbox, key_width=100
        )
        form.addRow(session_opts)

        # Show recording path preview

        form.setFieldGrowthPolicy(QFormLayout.AllNonFixedFieldsGrow)
        form.setRowWrapPolicy(QFormLayout.DontWrapRows)

        self.recording_path_preview = ElidingPathLabel("")
        # No need to assign mouseReleaseEvent: the label handles click-to-copy internally
        form.addRow("Will save to", self.recording_path_preview)
        # self.recording_path_preview = QLabel("")
        # # Ensure it never gets squished vertically
        # self.recording_path_preview.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Fixed)
        # self.recording_path_preview.setWordWrap(False)
        # self.recording_path_preview.setCursor(Qt.PointingHandCursor)
        # self.recording_path_preview.setToolTip("")  # will show the preview path
        # self.recording_path_preview.setTextInteractionFlags(Qt.TextSelectableByMouse)
        # self.recording_path_preview.mouseReleaseEvent = self._copy_path_on_click
        # form.addRow("Will save to", self.recording_path_preview)

        self.filename_edit = QLineEdit()
        form.addRow("Filename", self.filename_edit)

        # Container + codec + CRF in a single row
        grid = QGridLayout()
        grid.setContentsMargins(0, 2, 0, 2)
        grid.setHorizontalSpacing(8)

        grid.setColumnStretch(0, 0)
        grid.setColumnStretch(1, 3)
        grid.setColumnStretch(2, 0)
        grid.setColumnStretch(3, 3)
        grid.setColumnStretch(4, 0)
        grid.setColumnStretch(5, 2)

        ## Container
        container_label = QLabel("Container")
        container_label.setSizePolicy(QSizePolicy.Fixed, QSizePolicy.Preferred)
        grid.addWidget(container_label, 0, 0)

        self.container_combo = QComboBox()
        self.container_combo.setToolTip("Select the video container/format")
        self.container_combo.setSizePolicy(QSizePolicy.MinimumExpanding, QSizePolicy.Preferred)
        self.container_combo.setEditable(True)
        self.container_combo.addItems(sorted(ALLOWED_VIDEO_CONTAINERS))
        # Ensure it never becomes unreadable:
        self.container_combo.setMinimumContentsLength(8)
        self.container_combo.setSizeAdjustPolicy(QComboBox.SizeAdjustPolicy.AdjustToMinimumContentsLengthWithIcon)
        grid.addWidget(self.container_combo, 0, 1)

        ## Codec
        codec_label = QLabel("Codec")
        codec_label.setSizePolicy(QSizePolicy.Fixed, QSizePolicy.Preferred)
        grid.addWidget(codec_label, 0, 2)

        self.codec_combo = QComboBox()
        self.codec_combo.setToolTip("Select the video codec to use for recording")
        self.codec_combo.setSizePolicy(QSizePolicy.MinimumExpanding, QSizePolicy.Preferred)

        if os.sys.platform == "darwin":
            self.codec_combo.addItems(["h264_videotoolbox", "libx264", "hevc_videotoolbox"])
        else:
            self.codec_combo.addItems(["h264_nvenc", "libx264", "hevc_nvenc"])

        self.codec_combo.setCurrentText("libx264")
        # Optional: a modest minimum content length helps prevent jitter
        self.codec_combo.setMinimumContentsLength(6)
        self.codec_combo.setSizeAdjustPolicy(QComboBox.SizeAdjustPolicy.AdjustToMinimumContentsLengthWithIcon)
        grid.addWidget(self.codec_combo, 0, 3)

        ## CRF
        crf_label = QLabel("CRF")
        crf_label.setSizePolicy(QSizePolicy.MinimumExpanding, QSizePolicy.Preferred)
        grid.addWidget(crf_label, 0, 4)

        self.crf_spin = QSpinBox()
        self.crf_spin.setRange(0, 51)  # FFmpeg CRF range for x264/x265
        self.crf_spin.setValue(RecordingSettings().crf)
        self.crf_spin.setToolTip("Constant Rate Factor (0 = lossless, 51 = worst)")
        self.crf_spin.setSizePolicy(QSizePolicy.MinimumExpanding, QSizePolicy.Preferred)
        grid.addWidget(self.crf_spin, 0, 5)

        form.addRow(grid)

        # Recording options
        # self.record_with_overlays_checkbox = QCheckBox("Record video with overlays")
        # self.record_with_overlays_checkbox.setToolTip(
        # "Enable to include pose overlays in recorded video (keypoints & bounding boxes)"
        # )
        # self.record_with_overlays_checkbox.setChecked(False)

        self.fast_encoding_checkbox = QCheckBox("Use faster encoding parameters")
        self.fast_encoding_checkbox.setToolTip(
            "Use faster FFmpeg parameters for supported codecs.\n"
            "For libx264/libx265 this uses preset=ultrafast and tune=zerolatency.\n"
            "This can improve recording throughput but may increase file size."
        )
        self.fast_encoding_checkbox.setChecked(False)

        recording_options = QWidget()
        recording_options_layout = QHBoxLayout(recording_options)
        recording_options_layout.setContentsMargins(0, 0, 0, 0)
        # recording_options_layout.addWidget(self.record_with_overlays_checkbox)
        recording_options_layout.addWidget(self.fast_encoding_checkbox)
        recording_options_layout.addStretch(1)

        form.addRow(recording_options)

        # Wrap recording buttons in a widget to prevent shifting
        recording_button_widget = QWidget()
        buttons = QHBoxLayout(recording_button_widget)
        buttons.setContentsMargins(0, 0, 0, 0)
        self.start_record_button = QPushButton("Start recording")
        self.start_record_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_DialogYesButton))
        self.start_record_button.setMinimumWidth(150)
        buttons.addWidget(self.start_record_button)
        self.stop_record_button = QPushButton("Stop recording")
        self.stop_record_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_DialogNoButton))
        self.stop_record_button.setEnabled(False)
        self.stop_record_button.setMinimumWidth(150)
        buttons.addWidget(self.stop_record_button)
        form.addRow(recording_button_widget)

        # Add "Open folder" button
        self.open_rec_folder_button = QPushButton("Open recording folder")
        self.open_rec_folder_button.setIcon(self.style().standardIcon(QStyle.StandardPixmap.SP_DirOpenIcon))
        self.open_rec_folder_button.clicked.connect(self._action_open_recording_folder)
        form.addRow(self.open_rec_folder_button)

        return group

    def _build_viz_group(self) -> QGroupBox:
        group = QGroupBox("Visualization")
        form = QFormLayout(group)
        self.show_predictions_checkbox = QCheckBox("Display pose predictions")
        self.show_predictions_checkbox.setChecked(True)

        self.cmap_combo = color_ui.make_colormap_combo(
            current=self._colormap,
            tooltip="Select colormap to use when displaying keypoints (bodypart-based coloring)",
            favorites_first=["turbo", "jet", "hsv"],
            exclude_reversed=True,
            filters={"cet_": 5},  # include only first 5 colormaps from the 'cet_' family to avoid redundant options
            include_icons=True,
            sizing=color_ui.ComboSizing(min_width=80, max_width=200, popup_extra_padding=40),
        )

        keypoints_settings = lyts.make_two_field_row(
            "Keypoint colormap: ",
            self.cmap_combo,
            None,
            self.show_predictions_checkbox,
            key_width=120,
            left_stretch=0,
            right_stretch=0,
        )
        form.addRow(keypoints_settings)

        self.bbox_enabled_checkbox = QCheckBox("Show bounding box")
        self.bbox_enabled_checkbox.setChecked(False)

        self.bbox_color_combo = color_ui.make_bbox_color_combo(
            BBoxColors,
            current_bgr=self._bbox_color,
            include_icons=True,
            tooltip="Select color for bounding box",
            sizing=color_ui.ComboSizing(
                min_width=80,
                max_width=200,
            ),
        )

        bbox_settings = lyts.make_two_field_row(
            "Bounding box color: ",
            self.bbox_color_combo,
            None,
            self.bbox_enabled_checkbox,
            key_width=120,
            left_stretch=0,
            right_stretch=0,
        )
        form.addRow(bbox_settings)

        bbox_layout = QHBoxLayout()
        self.bbox_x0_spin = ScrubSpinBox()
        self.bbox_x0_spin.setRange(0, 7680)
        self.bbox_x0_spin.setPrefix("x0:")
        self.bbox_x0_spin.setValue(0)
        bbox_layout.addWidget(self.bbox_x0_spin)

        self.bbox_y0_spin = ScrubSpinBox()
        self.bbox_y0_spin.setRange(0, 4320)
        self.bbox_y0_spin.setPrefix("y0:")
        self.bbox_y0_spin.setValue(0)
        bbox_layout.addWidget(self.bbox_y0_spin)

        self.bbox_x1_spin = ScrubSpinBox()
        self.bbox_x1_spin.setRange(0, 7680)
        self.bbox_x1_spin.setPrefix("x1:")
        self.bbox_x1_spin.setValue(100)
        bbox_layout.addWidget(self.bbox_x1_spin)

        self.bbox_y1_spin = ScrubSpinBox()
        self.bbox_y1_spin.setRange(0, 4320)
        self.bbox_y1_spin.setPrefix("y1:")
        self.bbox_y1_spin.setValue(100)
        bbox_layout.addWidget(self.bbox_y1_spin)

        form.addRow("Coordinates", bbox_layout)

        return group

    # ------------------------------------------------------------------ signals
    def _connect_signals(self) -> None:
        self.preview_button.clicked.connect(self._start_preview)
        self.stop_preview_button.clicked.connect(self._stop_preview)
        self.start_record_button.clicked.connect(self._start_recording)
        self.stop_record_button.clicked.connect(self._stop_recording)
        self.start_inference_button.clicked.connect(self._start_inference)
        self.stop_inference_button.clicked.connect(lambda: self._stop_inference())
        self.show_predictions_checkbox.stateChanged.connect(self._on_show_predictions_changed)

        # Camera config dialog
        self.config_cameras_button.clicked.connect(self._open_camera_config_dialog)

        # Visualization settings
        ## Colormap change
        self.cmap_combo.currentIndexChanged.connect(self._on_colormap_changed)
        ## Connect bounding box controls
        self.bbox_enabled_checkbox.stateChanged.connect(self._on_bbox_changed)
        self.bbox_x0_spin.valueChanged.connect(self._on_bbox_changed)
        self.bbox_y0_spin.valueChanged.connect(self._on_bbox_changed)
        self.bbox_x1_spin.valueChanged.connect(self._on_bbox_changed)
        self.bbox_y1_spin.valueChanged.connect(self._on_bbox_changed)
        self.bbox_color_combo.currentIndexChanged.connect(self._on_bbox_color_changed)

        # Multi-camera controller signals (used for both single and multi-camera modes)
        self.multi_camera_controller.frame_ready.connect(self._on_multi_frame_processing_ready)
        self.multi_camera_controller.all_started.connect(self._on_multi_camera_started)
        self.multi_camera_controller.all_stopped.connect(self._on_multi_camera_stopped)
        self.multi_camera_controller.camera_error.connect(self._on_multi_camera_error)
        self.multi_camera_controller.initialization_failed.connect(self._on_multi_camera_initialization_failed)

        # DLC processor signals
        self._dlc.pose_ready.connect(self._on_pose_ready)
        self._dlc.error.connect(self._on_dlc_error)
        self._dlc.initialized.connect(self._on_dlc_initialised)
        self.dlc_camera_combo.currentIndexChanged.connect(self._on_dlc_camera_changed)
        self.dlc_camera_combo.currentTextChanged.connect(self.dlc_camera_combo.update_shrink_width)
        self.processor_combo.currentIndexChanged.connect(self._on_processor_selection_changed)
        self.use_custom_proc_checkbox.stateChanged.connect(self._on_custom_processor_enabled_changed)

        # Recording settings
        ## Session name persistence + preview updates
        self.session_name_edit.editingFinished.connect(self._on_session_name_editing_finished)
        self.filename_edit.editingFinished.connect(self._on_filename_editing_finished)
        self.use_timestamp_checkbox.stateChanged.connect(self._on_use_timestamp_changed)
        self.output_directory_edit.textChanged.connect(lambda _t: self._update_recording_path_preview())
        self.filename_edit.textChanged.connect(lambda _t: self._update_recording_path_preview())
        self.container_combo.currentTextChanged.connect(self._on_container_changed)
        self.fast_encoding_checkbox.stateChanged.connect(self._on_fast_encoding_changed)

    # ------------------------------------------------------------------
    # Config
    def _apply_config(self, config: ApplicationSettings, *, restore_local_prefs: bool = False) -> None:
        # Update active cameras label
        self._update_active_cameras_label()

        # Set DLC settings from config
        dlc = config.dlc
        resolved_model_path = self._model_path_store.resolve(dlc.model_path)
        self.model_path_edit.setText(resolved_model_path)

        # self.additional_options_edit.setPlainText(json.dumps(dlc.additional_options, indent=2))

        # Set recording settings from config
        recording = config.recording
        self.output_directory_edit.setText(recording.directory)
        self.filename_edit.setText(recording.filename)
        if restore_local_prefs:
            persisted_filename = self._settings_store.get_rec_filename()
            if persisted_filename:
                self.filename_edit.setText(persisted_filename)
        self.container_combo.setCurrentText(recording.container)
        codec_index = self.codec_combo.findText(recording.codec)
        if codec_index >= 0:
            self.codec_combo.setCurrentIndex(codec_index)
        else:
            self.codec_combo.addItem(recording.codec)
            self.codec_combo.setCurrentIndex(self.codec_combo.count() - 1)
        self.crf_spin.setValue(int(recording.crf))

        if hasattr(self, "fast_encoding_checkbox"):
            config_fast_encoding = bool(getattr(recording, "fast_encoding", False))
            self.fast_encoding_checkbox.setChecked(self._settings_store.get_fast_encoding(default=config_fast_encoding))

        ## Restore persisted session name if empty
        if hasattr(self, "session_name_edit"):
            if not self.session_name_edit.text().strip():
                persisted = self._settings_store.get_session_name()
                if persisted:
                    self.session_name_edit.setText(persisted)
        ## Restore "Use timestamp" checkbox state
        if hasattr(self, "use_timestamp_checkbox"):
            self.use_timestamp_checkbox.setChecked(self._settings_store.get_use_timestamp(default=True))

        # Set bounding box settings from config
        bbox = config.bbox
        self.bbox_enabled_checkbox.setChecked(bbox.enabled)
        self.bbox_x0_spin.setValue(bbox.x0)
        self.bbox_y0_spin.setValue(bbox.y0)
        self.bbox_x1_spin.setValue(bbox.x1)
        self.bbox_y1_spin.setValue(bbox.y1)

        # Set visualization settings from config
        viz = config.visualization
        self._p_cutoff = viz.p_cutoff
        self._colormap = viz.colormap
        if hasattr(self, "cmap_combo"):
            color_ui.set_cmap_combo_from_name(self.cmap_combo, self._colormap, fallback="viridis")
        self._bbox_color = viz.get_bbox_color_bgr()
        if hasattr(self, "bbox_color_combo"):
            color_ui.set_bbox_combo_from_bgr(self.bbox_color_combo, self._bbox_color)

        # Processor
        ## Use custom processor checkbox state
        if hasattr(self, "use_custom_proc_checkbox"):
            self.use_custom_proc_checkbox.setChecked(self._settings_store.get_processor_control_enabled(default=False))

        # Update DLC camera list
        self._refresh_dlc_camera_list()

        # Update recording path preview
        self._update_recording_path_preview()

    def _current_config(self, *, allow_empty_model_path=False) -> ApplicationSettings:
        multi_camera = self._config.multi_camera
        active_cameras = multi_camera.get_active_cameras()
        camera = (
            active_cameras[0].model_copy(deep=True)
            if active_cameras
            else (
                multi_camera.cameras[0].model_copy(deep=True)
                if multi_camera.cameras
                else self._config.camera.model_copy(deep=True)
            )
        )

        return ApplicationSettings(
            camera=camera,
            multi_camera=multi_camera,
            dlc=self._dlc_settings_from_ui(allow_empty_model_path=allow_empty_model_path),
            recording=self._recording_settings_from_ui(),
            bbox=self._bbox_settings_from_ui(),
            visualization=self._visualization_settings_from_ui(),
        )

    def _parse_json(self, value: str) -> dict:
        text = value.strip()
        if not text:
            return {}
        return json.loads(text)

    def _dlc_settings_from_ui(self, *, allow_empty_model_path=False) -> DLCProcessorSettings:
        model_path = self.model_path_edit.text().strip()
        if Path(model_path).exists() and Path(model_path).suffix == ".pb":
            # IMPORTANT NOTE: DLClive expects a directory for TensorFlow models,
            # so if user selects a .pb file, we should pass the parent directory to DLCLive
            model_path = str(Path(model_path).parent)

        existing_dlc = (  # explicitly init from default if unset
            self._config.dlc.model_copy(deep=True)
            if getattr(self._config, "dlc", None) is not None
            else DEFAULT_CONFIG.dlc.model_copy(deep=True)
        )
        if not model_path:
            if allow_empty_model_path:
                # Preserve all existing DLC settings and only clear the model path.
                return existing_dlc.model_copy(
                    update={
                        "model_path": "",
                    }
                )

            raise ValueError("Model path cannot be empty. Please enter a valid path to a DLCLive model file.")

        try:
            model_bknd = DLCLiveProcessor.get_model_backend(model_path)
        except Exception as e:
            raise RuntimeError(
                "Could not determine model backend from path. "
                "Please ensure the model file is valid and has an appropriate extension "
                "(.pt, .pth for PyTorch or model directory for TensorFlow)."
            ) from e

        # Preserve all unchanged DLC settings and only update values derived from the UI
        updated_dlc = existing_dlc.model_dump()
        updated_dlc.update(
            {
                "model_path": model_path,
                "model_type": model_bknd,
            }
        )
        return DLCProcessorSettings.model_validate(updated_dlc)

    def _recording_settings_from_ui(self) -> RecordingSettings:
        container = self.container_combo.currentText().strip() or DEFAULT_RECORDING_CONTAINER
        filename = self._filename_matching_container(self.filename_edit.text().strip(), container)
        return RecordingSettings(
            enabled=True,  # Always enabled - recording controlled by button
            directory=self.output_directory_edit.text().strip(),
            filename=filename,
            container=container,
            codec=self.codec_combo.currentText().strip() or "libx264",
            crf=int(self.crf_spin.value()),
            fast_encoding=bool(
                getattr(self, "fast_encoding_checkbox", None) and self.fast_encoding_checkbox.isChecked()
            ),
        )

    def _bbox_settings_from_ui(self) -> BoundingBoxSettings:
        return BoundingBoxSettings(
            enabled=self.bbox_enabled_checkbox.isChecked(),
            x0=self.bbox_x0_spin.value(),
            y0=self.bbox_y0_spin.value(),
            x1=self.bbox_x1_spin.value(),
            y1=self.bbox_y1_spin.value(),
        )

    def _visualization_settings_from_ui(self) -> VisualizationSettings:
        return VisualizationSettings(
            p_cutoff=self._p_cutoff,
            colormap=self._colormap,
            bbox_color=self._bbox_color,
        )

    def _suggest_config_dialog_path(self) -> str:
        """Return best initial path for load/save config dialogs."""
        if getattr(self, "_config_path", None) is not None:
            try:
                return str(self._config_path)
            except Exception:
                pass

        last_cfg = self._settings_store.get_last_config_path()
        valid_last = self._valid_config_file_path(last_cfg)
        if valid_last is not None:
            return str(valid_last)

        if last_cfg:
            try:
                p = Path(last_cfg).expanduser()
                parent = p.parent
                if parent.exists() and parent.is_dir():
                    return str(parent / (p.name or "config.json"))
            except Exception:
                logger.debug("Failed to derive config dialog path from %s", last_cfg, exc_info=True)

        return str(Path.home() / "config.json")

    # ------------------------------------------------------------------
    # Actions
    def _action_load_config(self) -> None:
        file_name, _ = QFileDialog.getOpenFileName(
            self, "Load configuration", self._suggest_config_dialog_path(), "JSON files (*.json)"
        )
        if not file_name:
            return
        try:
            config = ApplicationSettings.load(file_name)
        except Exception as exc:  # pragma: no cover - GUI interaction
            self._show_error(str(exc))
            return
        self._settings_store.set_last_config_path(file_name)
        self._settings_store.save_full_config_snapshot(config)

        try:
            self.settings.sync()
        except Exception:
            logger.debug("Failed to sync settings after loading config", exc_info=True)

        self._config = config
        self._config_path = Path(file_name)
        self._apply_config(config)
        self.statusBar().showMessage(f"Loaded configuration: {file_name}", 5000)
        # Validate cameras after loading
        self._validate_configured_cameras()

    def _action_save_config(self) -> None:
        if self._config_path is None:
            self._action_save_config_as()
            return
        if self._save_config_to_path(self._config_path):
            self._config_path = self._config_path.expanduser()

    def _action_save_config_as(self) -> None:
        file_name, _ = QFileDialog.getSaveFileName(
            self, "Save configuration", self._suggest_config_dialog_path(), "JSON files (*.json)"
        )
        if not file_name:
            return
        path = Path(file_name).expanduser()
        if path.suffix.lower() != ".json":
            path = path.with_suffix(".json")
        if self._save_config_to_path(path):
            self._config_path = path

    def _save_config_to_path(self, path: Path) -> bool:
        try:
            config = self._current_config(allow_empty_model_path=True)
            config.save(path)
            self._settings_store.set_last_config_path(str(path))
            self._settings_store.save_full_config_snapshot(config)

            try:
                self.settings.sync()
            except Exception:
                logger.debug("Failed to sync settings after saving config", exc_info=True)

        except Exception as exc:  # pragma: no cover - GUI interaction
            self._show_error(str(exc))
            return False
        self.statusBar().showMessage(f"Saved configuration to {path}", 5000)
        return True

    def _action_browse_model(self) -> None:
        # Prefer persisted last-used directory, then config.dlc.model_directory, then home
        start_dir = self._model_path_store.suggest_start_dir(self._config.dlc.model_directory)
        preselect = self._model_path_store.suggest_selected_file()

        dlg = QFileDialog(self, "Select DLCLive model file")
        dlg.setFileMode(QFileDialog.FileMode.ExistingFile)
        dlg.setNameFilters(
            [
                "Model files (*.pt *.pth)",
                "PyTorch models (*.pt *.pth)",
                "TensorFlow models (*.pb)",
            ]
        )
        dlg.setDirectory(start_dir)

        # Preselect last used model if it exists (optional but nice)
        if preselect:
            dlg.selectFile(preselect)

        if dlg.exec():
            selected = dlg.selectedFiles()
            if not selected:
                return
            file_path = Path(selected[0]).expanduser()
            if not file_path.exists():
                QMessageBox.warning(self, "File not found", f"The selected file does not exist:\n{file_path}")
                return

            try:
                if file_path.suffix == ".pb":
                    # For TensorFlow, DLCLive expects a directory, so we pass the parent directory for validation
                    model_check_path = file_path.parent
                else:
                    model_check_path = file_path
                # Raise if the model backend cannot be determined (invalid file or unsupported extension)
                DLCLiveProcessor.get_model_backend(str(model_check_path))
            except FileNotFoundError as e:
                QMessageBox.warning(self, "Model selection error", str(e))
                return
            except ValueError as e:
                QMessageBox.warning(self, "Model selection error", str(e))
                return
            file_path = str(file_path)
            self.model_path_edit.setText(file_path)

            # Persist model path + directory
            self._model_path_store.save_if_valid(file_path)

            # Optional: update config so next startup uses this directory too
            try:
                self._config.dlc.model_directory = str(Path(file_path).parent)
            except Exception:
                pass

    def _action_browse_directory(self) -> None:
        directory = QFileDialog.getExistingDirectory(self, "Select output directory", str(Path.home()))
        if directory:
            self.output_directory_edit.setText(directory)

    def _action_browse_processor_folder(self) -> None:
        """Browse for processor folder."""
        current_path = self.processor_folder_edit.text().strip() or default_processors_dir()
        directory = QFileDialog.getExistingDirectory(self, "Select processor folder", current_path)
        if directory:
            self.processor_folder_edit.setText(directory)
            self._settings_store.set_processor_folder(directory)
            self._refresh_processors()

    def _action_open_recording_folder(self) -> None:
        """
        Open the recording folder in the system file explorer.
        Priority:
            1. If a run directory exists (during/after recording), open it.
            2. Else if the session directory exists, open it.
            3. Else if the base output directory exists, open it.
            4. Otherwise: show warning.
        """
        try:
            # 1. Real run directory if available (RecordingManager)
            run_dir = getattr(self._rec_manager, "run_dir", None)
            if run_dir and Path(run_dir).exists():
                target = Path(run_dir)
            else:
                # 2. Session folder
                out_dir = Path(self.output_directory_edit.text().strip()).expanduser()
                sess_name = self.session_name_edit.text().strip() or "session"
                sess_dir = out_dir / sess_name

                if sess_dir.exists():
                    target = sess_dir
                elif out_dir.exists():
                    target = out_dir
                else:
                    self.statusBar().showMessage("Recording folder does not exist yet.", 5000)
                    return

            # --- Use Qt's built-in cross-platform folder opener ---
            url = QUrl.fromLocalFile(str(target))
            ok = QDesktopServices.openUrl(url)

            if ok:
                self.statusBar().showMessage(f"Opened folder: {target}", 3000)
            else:
                self.statusBar().showMessage("Could not open folder.", 5000)

        except Exception as exc:
            logger.error(f"Failed to open folder: {exc}")
            self.statusBar().showMessage("Could not open recording folder.", 5000)

    def _action_view_documentation(self) -> None:
        """Open the DeepLabCut-live-GUI documentation."""
        url = QUrl("https://deeplabcut.github.io/DeepLabCut/docs/dlc-live/dlc-live-gui/index.html")
        if not QDesktopServices.openUrl(url):
            self._show_warning("Could not open the documentation in your web browser.")

    def _custom_processor_enabled(self) -> bool:
        return bool(
            getattr(self, "use_custom_proc_checkbox", None)
            and self.use_custom_proc_checkbox.isChecked()
            and self.processor_combo.currentData() is not None
        )

    def _on_processor_selection_changed(
        self,
        _index: int,
    ) -> None:
        """Persist selection and enable custom processing for a chosen processor."""
        selected_key = self.processor_combo.currentData()
        has_selection = selected_key is not None

        self._settings_store.set_processor_key(selected_key)
        self.processor_toggle_row.setVisible(has_selection)

        self.use_custom_proc_checkbox.blockSignals(True)
        self.use_custom_proc_checkbox.setChecked(has_selection)
        self.use_custom_proc_checkbox.blockSignals(False)

        self._settings_store.set_processor_control_enabled(has_selection)

        if hasattr(
            self.processor_combo,
            "update_shrink_width",
        ):
            self.processor_combo.update_shrink_width()

        self._update_processor_status()

    def _on_custom_processor_enabled_changed(
        self,
        _state: int,
    ) -> None:
        """Persist whether the selected custom processor should be used."""
        enabled = self._custom_processor_enabled()

        self._settings_store.set_processor_control_enabled(enabled)
        self._update_processor_status()

    def _refresh_processors(self) -> None:
        """Scan processors and restore the previous selection best-effort."""
        previous_key = self.processor_combo.currentData()
        preferred_key = previous_key or self._settings_store.get_processor_key()
        preferred_enabled = (
            self.use_custom_proc_checkbox.isChecked()
            if previous_key is not None
            else self._settings_store.get_processor_control_enabled(default=False)
        )

        self.processor_combo.blockSignals(True)
        try:
            self.processor_combo.clear()
            self.processor_combo.addItem(
                "No Processor",
                None,
            )

            selected_folder = self.processor_folder_edit.text().strip()
            selected_path = Path(selected_folder).expanduser() if selected_folder else None

            if selected_path is not None and selected_path.is_dir():
                resolved_folder = str(selected_path.resolve())
                self._settings_store.set_processor_folder(resolved_folder)
                self._scanned_processors = scan_processor_folder(resolved_folder)
                source_text = resolved_folder
            else:
                self._scanned_processors = scan_processor_package("dlclivegui.processors")
                source_text = "package dlclivegui.processors"

            self._processor_keys = list(self._scanned_processors)

            for key in self._processor_keys:
                info = self._scanned_processors[key]
                display_name = f"{info['name']} ({info['file']})"
                self.processor_combo.addItem(
                    display_name,
                    key,
                )

            selected_index = 0
            if preferred_key is not None:
                found_index = self.processor_combo.findData(preferred_key)
                if found_index >= 0:
                    selected_index = found_index

            self.processor_combo.setCurrentIndex(selected_index)
        finally:
            self.processor_combo.blockSignals(False)

        has_selection = self.processor_combo.currentData() is not None

        self.processor_toggle_row.setVisible(has_selection)

        self.use_custom_proc_checkbox.blockSignals(True)
        self.use_custom_proc_checkbox.setChecked(has_selection and preferred_enabled)
        self.use_custom_proc_checkbox.blockSignals(False)

        # Clear a saved key that is no longer available.
        selected_key = self.processor_combo.currentData()
        self._settings_store.set_processor_key(selected_key)
        self._settings_store.set_processor_control_enabled(self._custom_processor_enabled())

        self.processor_combo.update_shrink_width()
        self._update_processor_status()

        self.statusBar().showMessage(
            f"Found {len(self._processor_keys)} processor(s) in {source_text}",
            3000,
        )

    # ------------------------------------------------------------------
    # Recording path preview and session name persistence
    def _known_recording_extensions(self) -> set[str]:
        """Return known recording container extensions without leading dots."""
        known = ALLOWED_VIDEO_CONTAINERS.copy()
        if hasattr(self, "container_combo"):
            known.update(
                self.container_combo.itemText(i).strip().lower().lstrip(".")
                for i in range(self.container_combo.count())
                if self.container_combo.itemText(i).strip()
            )
        return known

    def _filename_matching_container(self, filename: str, container: str) -> str:
        """
        Adjust filename extension to match selected container, but only when
        the existing extension is another known recording container.
        """
        name = filename.strip() or "recording"
        selected_ext = container.strip().lower().lstrip(".")
        suffix = Path(name).suffix

        if not suffix or not selected_ext:
            return name

        current_ext = suffix.lower().lstrip(".")
        if current_ext in self._known_recording_extensions() and current_ext != selected_ext:
            return str(Path(name).with_suffix(f".{selected_ext}"))

        return name

    def _on_container_changed(self, text: str) -> None:
        """Keep filename extension aligned with selected container when safe."""
        if hasattr(self, "filename_edit"):
            current = self.filename_edit.text()
            updated = self._filename_matching_container(current, text)
            if updated != current:
                self.filename_edit.blockSignals(True)
                self.filename_edit.setText(updated)
                self.filename_edit.blockSignals(False)

        self._update_recording_path_preview()

    def _on_session_name_editing_finished(self) -> None:
        name = self.session_name_edit.text().strip()
        self._settings_store.set_session_name(name)
        self._update_recording_path_preview()

    def _on_filename_editing_finished(self) -> None:
        filename = self.filename_edit.text().strip()
        self._settings_store.set_rec_filename(filename)
        self._update_recording_path_preview()

    def _update_recording_path_preview(self) -> None:
        """Update the label showing where files will go (best-effort)."""
        if not hasattr(self, "recording_path_preview"):
            return

        out_dir = self.output_directory_edit.text().strip()
        sess = self.session_name_edit.text().strip() if hasattr(self, "session_name_edit") else ""
        container = (
            self.container_combo.currentText().strip()
            if hasattr(self, "container_combo")
            else DEFAULT_RECORDING_CONTAINER
        )
        base = self._filename_matching_container(self.filename_edit.text(), container)
        use_ts = self.use_timestamp_checkbox.isChecked() if hasattr(self, "use_timestamp_checkbox") else True

        # Preview is approximate (since run index/time is decided at start).
        sess_safe = sess or "session"
        run_hint = "run_<timestamp>" if use_ts else "run_<next>"
        stem_hint = Path(base).stem if base else "recording"
        full_hint = str(Path(out_dir).expanduser() / sess_safe / run_hint / f"{stem_hint}_<camera>.{container}")

        self.recording_path_preview.set_full_text(full_hint)

    # def _copy_path_on_click(self, event):
    #     if event.button() == Qt.LeftButton:
    #         # Clear all HTML tags to get the raw path before copying
    #         path = self.recording_path_preview.text()
    #         path = path.replace("<span style='color: gray;'>", "").replace("</span>", "")
    #         clean_path = path.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
    #         QGuiApplication.clipboard().setText(clean_path)
    #         QToolTip.showText(QCursor.pos(), "Copied path", self.recording_path_preview)

    def _on_use_timestamp_changed(self, _state: int) -> None:
        self._settings_store.set_use_timestamp(self.use_timestamp_checkbox.isChecked())
        self._update_recording_path_preview()

    def _on_fast_encoding_changed(self, _state: int) -> None:
        self._settings_store.set_fast_encoding(self.fast_encoding_checkbox.isChecked())

    def _on_colormap_changed(self, _index: int) -> None:
        self._colormap = color_ui.get_cmap_name_from_combo(self.cmap_combo, fallback=self._colormap)
        if self._current_frame is not None:
            self._display_frame(self._current_frame, force=True)

    def _on_bbox_color_changed(self, _index: int) -> None:
        bgr = color_ui.get_bbox_bgr_from_combo(self.bbox_color_combo, fallback=self._bbox_color)
        if bgr is None:
            return
        self._bbox_color = bgr
        if self._current_frame is not None:
            self._display_frame(self._current_frame, force=True)

    # ------------------------------------------------------------------
    # Multi-camera
    def _open_camera_config_dialog(self) -> None:
        """Open the camera configuration dialog (non-modal, async inside)."""
        if self.multi_camera_controller.is_running():
            self._show_warning("Stop the main preview before configuring cameras.")
            return

        if self._cam_dialog is None:
            self._cam_dialog = CameraConfigDialog(self, self._config.multi_camera)
            self._cam_dialog.settings_changed.connect(self._on_multi_camera_settings_changed)
        else:
            self._cam_dialog.set_settings(self._config.multi_camera, dlc_camera_id=self._inference_camera_id)

        self._cam_dialog.show()
        self._cam_dialog.raise_()
        self._cam_dialog.activateWindow()

    def _on_multi_camera_settings_changed(self, settings: MultiCameraSettings) -> None:
        """Handle changes to multi-camera settings."""
        self._config.multi_camera = settings
        self._update_active_cameras_label()
        self._refresh_dlc_camera_list()
        active_count = len(settings.get_active_cameras())
        self.statusBar().showMessage(f"Camera configuration updated: {active_count} active camera(s)", 3000)

    def _update_active_cameras_label(self) -> None:
        active_cams = self._config.multi_camera.get_active_cameras()

        if not active_cams:
            self.active_cameras_label.setText("No cameras configured")
            return

        if len(active_cams) == 1:
            cam = active_cams[0]
            display_id = get_display_id(cam)
            self.active_cameras_label.setText(f"{display_id} [{cam.backend}:{cam.index}]")
            return

        cam_names = [get_display_id(c) for c in active_cams]
        self.active_cameras_label.setText(f"{len(active_cams)} cameras: {', '.join(cam_names)}")

    def _validate_configured_cameras(self) -> None:
        """Validate that configured cameras are available.

        Disables unavailable cameras and shows a warning dialog.
        """
        if getattr(self._cam_dialog, "_dialog_active", False):
            # Skip validation if camera config dialog is open
            return

        active_cams = self._config.multi_camera.get_active_cameras()
        if not active_cams:
            return

        unavailable: list[tuple[str, str, CameraSettings]] = []
        for cam in active_cams:
            cam_id = f"{cam.backend}:{cam.index}"
            available, error = CameraFactory.check_camera_available(cam)
            if not available:
                unavailable.append((cam.name or cam_id, error, cam))

        if unavailable:
            # Disable unavailable cameras
            for _, _, cam in unavailable:
                cam.enabled = False

            # Update the active cameras label
            self._update_active_cameras_label()

            # Build warning message
            error_lines = ["The following camera(s) are not available and have been disabled:"]
            for cam_name, error_msg, _ in unavailable:
                error_lines.append(f"  • {cam_name}: {error_msg}")
            error_lines.append("")
            error_lines.append("Please check camera connections or re-enable in camera settings.")
            self._show_warning("\n".join(error_lines))
            logger.warning("\n".join(error_lines))

    def _label_for_cam_id(self, cam_id: str) -> str:
        for cam in self._config.multi_camera.get_active_cameras():
            if get_camera_id(cam) == cam_id:
                display_id = get_display_id(cam)
                return f"{display_id} [{cam.backend}:{cam.index}]"

        display_id = self._multi_camera_display_ids.get(cam_id)
        if display_id:
            return display_id

        return f"Unknown camera [{cam_id}]"

    def _refresh_dlc_camera_list_running(self) -> None:
        """Populate inference camera dropdown from currently running cameras.

        - Keep the user's preferred camera if it is running
        - Otherwise use a temporary runtime fallback
        - Never persist fallback choices caused by preview/update events
        """
        preferred_id = self._inference_camera_id or self._settings_store.get_inference_camera_id()

        self.dlc_camera_combo.blockSignals(True)
        self.dlc_camera_combo.clear()

        for cam in self._config.multi_camera.get_active_cameras():
            cam_id = get_camera_id(cam)
            if cam_id in self._running_cams_ids:
                self.dlc_camera_combo.addItem(self._label_for_cam_id(cam_id), cam_id)

        selected_id = None

        if preferred_id in self._running_cams_ids:
            idx = self.dlc_camera_combo.findData(preferred_id)
            if idx >= 0:
                self.dlc_camera_combo.setCurrentIndex(idx)
                selected_id = preferred_id

        if selected_id is None and self.dlc_camera_combo.count() > 0:
            self.dlc_camera_combo.setCurrentIndex(0)
            selected_id = self.dlc_camera_combo.currentData()

        self._active_inference_camera_id = selected_id

        self.dlc_camera_combo.blockSignals(False)
        self.dlc_camera_combo.update_shrink_width()

    def _set_dlc_combo_to_id(self, cam_id: str) -> bool:
        """Update combo selection to a given camera ID without firing signals."""
        self.dlc_camera_combo.blockSignals(True)
        try:
            idx = self.dlc_camera_combo.findData(cam_id)
            if idx >= 0:
                self.dlc_camera_combo.setCurrentIndex(idx)
                return True
            return False
        finally:
            self.dlc_camera_combo.blockSignals(False)
            self.dlc_camera_combo.update_shrink_width()

    def _refresh_dlc_camera_list(self) -> None:
        """Populate inference camera dropdown from configured active cameras."""
        preferred_id = self._inference_camera_id or self._settings_store.get_inference_camera_id()

        self.dlc_camera_combo.blockSignals(True)
        self.dlc_camera_combo.clear()

        active_cams = self._config.multi_camera.get_active_cameras()
        for cam in active_cams:
            cam_id = get_camera_id(cam)
            display_id = get_display_id(cam)
            label = f"{display_id} [{cam.backend}:{cam.index}]"
            self.dlc_camera_combo.addItem(label, cam_id)

        selected_id = None

        if preferred_id is not None:
            idx = self.dlc_camera_combo.findData(preferred_id)
            if idx >= 0:
                self.dlc_camera_combo.setCurrentIndex(idx)
                selected_id = preferred_id

        if selected_id is None and self.dlc_camera_combo.count() > 0:
            self.dlc_camera_combo.setCurrentIndex(0)
            selected_id = self.dlc_camera_combo.currentData()

            # First-run convenience only.
            # If there is no previous preference, initialize one.
            if self._inference_camera_id is None and preferred_id is None:
                self._inference_camera_id = selected_id
                self._settings_store.set_inference_camera_id(selected_id)

        self._active_inference_camera_id = selected_id

        self.dlc_camera_combo.blockSignals(False)
        self.dlc_camera_combo.update_shrink_width()

    def _on_dlc_camera_changed(self, _index: int) -> None:
        """Track explicit user selection of the inference camera."""
        cam_id = self.dlc_camera_combo.currentData()

        self._inference_camera_id = cam_id
        self._active_inference_camera_id = cam_id

        self._settings_store.set_inference_camera_id(cam_id)

        self.dlc_camera_combo.update_shrink_width()

        # Force redraw so bbox/pose overlays switch to the new tile immediately.
        if self._current_frame is not None:
            self._display_frame(self._current_frame, force=True)

    # ------------------------------------------------------------------
    # Multi-camera event handlers
    def _render_overlays_for_recording(self, cam_id, frame):
        # Copy so we don't affect GUI preview pipeline
        output = frame.copy()
        offset, scale = (0, 0), (1.0, 1.0)

        # If this is the inference camera, apply pose overlays
        if cam_id == self._active_inference_camera_id and self._last_pose and self._last_pose.pose is not None:
            output = draw_pose(
                output,
                self._last_pose.pose,
                p_cutoff=self._p_cutoff,
                colormap=self._colormap,
                offset=offset,
                scale=scale,
            )
        if self._bbox_enabled:
            output = draw_bbox(
                frame=output,
                bbox_xyxy=(self._bbox_x0, self._bbox_y0, self._bbox_x1, self._bbox_y1),
                color_bgr=self._bbox_color,
                offset=offset,
                scale=scale,
            )
        return output

    def _on_multi_frame_processing_ready(self, frame_data: MultiFrameData) -> None:
        """Handle frames from multiple cameras.

        Priority:
            - DLC processing (highest priority - enqueue immediately, only for DLC camera)
        """
        self._multi_camera_frames = frame_data.frames
        self._multi_camera_display_ids = frame_data.display_ids or {}
        self._display_dirty = True
        self._try_start_pending_recording()
        src_id = frame_data.source_camera_id
        if src_id:
            self._fps_tracker.note_frame(src_id)  # Track FPS

        new_running = set(frame_data.frames.keys())
        if new_running != self._running_cams_ids:
            self._running_cams_ids = new_running
            self._refresh_dlc_camera_list_running()

        preferred_id = self._inference_camera_id
        available_ids = list(frame_data.frames.keys())

        if preferred_id in frame_data.frames:
            dlc_cam_id = preferred_id
        else:
            dlc_cam_id = available_ids[0] if available_ids else ""

            if dlc_cam_id:
                if self._active_inference_camera_id != dlc_cam_id:
                    self._active_inference_camera_id = dlc_cam_id
                    self._set_dlc_combo_to_id(dlc_cam_id)
                    self.statusBar().showMessage(
                        f"Using temporary DLC inference camera: {self._label_for_cam_id(dlc_cam_id)}",
                        3000,
                    )
            else:
                if self._dlc_active:
                    self._stop_inference(show_message=True)
                self._display_dirty = True
                return

        self._active_inference_camera_id = dlc_cam_id

        # Check if this frame is from the DLC camera
        is_dlc_camera_frame = frame_data.source_camera_id == dlc_cam_id

        # Update tile info and raw frame only when DLC camera frame arrives
        if is_dlc_camera_frame and dlc_cam_id in frame_data.frames:
            frame = frame_data.frames[dlc_cam_id]
            self._raw_frame = frame
            self._dlc_tile_offset, self._dlc_tile_scale = compute_tile_info(dlc_cam_id, frame, frame_data.frames)

        # PRIORITY: DLC processing - only enqueue when DLC camera frame arrives!
        if self._dlc_active and is_dlc_camera_frame and dlc_cam_id in frame_data.frames:
            frame = frame_data.frames[dlc_cam_id]
            timestamp = frame_data.timestamps.get(dlc_cam_id, time.time())
            with self._dlc_timing.measure("enqueue_frame"):
                self._dlc.enqueue_frame(frame, timestamp)

            self._dlc_timing.note_frame()
            self._dlc_timing.maybe_log()

    def _on_multi_camera_started(self) -> None:
        """Handle all cameras started event."""
        self.preview_button.setEnabled(False)
        self.stop_preview_button.setEnabled(True)
        active_count = self.multi_camera_controller.get_active_count()
        self.statusBar().showMessage(f"Multi-camera preview started: {active_count} camera(s)", 5000)
        self._update_inference_buttons()
        self._update_camera_controls_enabled()
        self._update_dlc_controls_enabled()

    def _on_multi_camera_stopped(self) -> None:
        """Handle all cameras stopped event."""
        # Stop all multi-camera recorders
        self._stop_multi_camera_recording()
        self._pending_recording_after_preview = False

        self.preview_button.setEnabled(True)
        self.stop_preview_button.setEnabled(False)

        self._current_frame = None
        self._multi_camera_frames.clear()
        self._multi_camera_display_ids.clear()
        self._running_cams_ids.clear()
        self._display_dirty = False

        self.video_label.setPixmap(QPixmap())
        self.video_label.setText("Camera preview not started")
        self.statusBar().showMessage("Multi-camera preview stopped", 3000)

        self._update_active_cameras_label()
        self._refresh_dlc_camera_list()
        self._update_inference_buttons()
        self._update_camera_controls_enabled()
        self._update_dlc_controls_enabled()

    def _on_multi_camera_error(self, camera_id: str, message: str) -> None:
        """Handle error from a camera in multi-camera mode."""
        self._pending_recording_after_preview = False
        self._show_warning(f"Camera {camera_id} error: {message}\nRecording stopped.")
        self._refresh_dlc_camera_list_running()
        if self.dlc_camera_combo.count() <= 1:
            self._stop_inference()  # We now gracefully switch DLC camera if needed, but if none left, stop inference
        self._stop_recording()

    def _on_multi_camera_initialization_failed(self, failures: list) -> None:
        """Handle complete failure to initialize cameras."""
        self._pending_recording_after_preview = False
        # Build error message with details for each failed camera
        error_lines = ["Failed to initialize camera(s):"]
        for camera_id, error_msg in failures:
            error_lines.append(f"  • {camera_id}: {error_msg}")
        error_lines.append("")
        error_lines.append("Please check that the required camera backend is installed.")

        error_message = "\n".join(error_lines)
        self._show_error(error_message)
        logger.error(error_message)

    def _start_multi_camera_recording(self) -> None:
        """Start recording from all active cameras."""
        recording = self._recording_settings_from_ui()
        active_cams = self._config.multi_camera.get_active_cameras()
        if not active_cams:
            self._show_error("No active cameras to record from.")
            return

        session_name = self.session_name_edit.text().strip() if hasattr(self, "session_name_edit") else ""
        use_ts = self.use_timestamp_checkbox.isChecked() if hasattr(self, "use_timestamp_checkbox") else True
        actual_fps_by_camera = self.multi_camera_controller.actual_fps_by_camera_id()

        run_dir = self._rec_manager.start_all(
            recording,
            active_cams,
            self._multi_camera_frames,
            frame_rates=actual_fps_by_camera,
            session_name=session_name,
            use_timestamp=use_ts,
            all_or_nothing=False,
        )
        if run_dir is None:
            self._show_error("Failed to start recording.")
            return

        self._processor_recording_context = self._build_processor_recording_context(run_dir)
        self._processor_recording_started_notified = False
        self._notify_processor_recording_started(self._processor_recording_context)
        self.multi_camera_controller.set_recording_sink(self._rec_manager.write_frame)
        self.multi_camera_controller.set_recording_frame_is_enabled(True)

        self._settings_store.set_session_name(session_name)
        self.start_record_button.setEnabled(False)
        self.stop_record_button.setEnabled(True)
        self.statusBar().showMessage(f"Recording {len(active_cams)} camera(s) to {run_dir}", 5000)
        self._update_camera_controls_enabled()

    def _stop_multi_camera_recording(self) -> None:
        if not self._rec_manager.is_active:
            return

        if getattr(self, "_recording_stopping", False):
            return

        self._recording_stopping = True

        self.start_record_button.setEnabled(False)
        self.stop_record_button.setEnabled(False)
        self.statusBar().showMessage("Stopping multi-camera recording…", 3000)

        # Stop frame emission immediately so no new frames enter recording pipeline.
        try:
            self.multi_camera_controller.set_recording_frame_is_enabled(False)
            self.multi_camera_controller.set_recording_sink(None)
        except Exception:
            logger.exception("Failed to disable recording frame emission")

        def worker():
            total_wait_time = 0.0
            try:
                while not self._rec_manager.stop_all():
                    logger.info("Retrying recorder stop...")
                    time.sleep(RECORD_STOP_RETRY_INTERVAL)
                    total_wait_time += RECORD_STOP_RETRY_INTERVAL
                    if total_wait_time >= RECORD_STOP_RETRY_TIMEOUT:
                        logger.error("Timeout while stopping recording after %.1f seconds", total_wait_time)
                        raise RuntimeError("Could not stop recording within timeout period.")
            except Exception as e:
                logger.exception("Error while stopping recording: %s", e)
                self._rec_stop_failed_async.emit(str(e))
                return

            self._recording_stopped_async.emit()

        threading.Thread(
            target=worker,
            name="StopRecordingWorker",
            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.

        The GUI intentionally does not pass a path here. This lets custom processors
        use their own save_path / filename / internal policy.

        Expected processor contract:
            processor.save() -> int | bool | None

        Return values are only logged; failure should not crash the GUI.
        """
        processor = self._get_dlc_processor_instance()

        if processor is None:
            logger.debug("Processor save skipped: no processor instance available.")
            return

        save = getattr(processor, "save", None)
        if not callable(save):
            logger.debug("Processor save skipped: processor has no callable save().")
            return

        try:
            result = save()
            logger.info("Processor save() completed with result: %r", result)
        except Exception:
            logger.exception("Processor save() failed.")

    def _notify_processor_recording_started(self, context: dict) -> bool:
        processor = self._get_dlc_processor_instance()
        if processor is None:
            return False

        hook = getattr(processor, "on_recording_started", None)
        if not callable(hook):
            return False

        try:
            hook(context)
            self._processor_recording_started_notified = True
            logger.info("Notified processor recording started: %s", context)
            return True
        except Exception:
            logger.exception("Processor on_recording_started hook failed")
            return False

    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 _final_processor_recording_context(self) -> dict:
        cached = self._processor_recording_context

        run_dir = None
        if cached is not None:
            run_dir = cached.get("run_dir")
        if run_dir is None:
            run_dir = getattr(self._rec_manager, "run_dir", None)

        context = self._build_processor_recording_context(run_dir)
        if cached is not None:
            context.update(cached)

        try:
            final_file_context = self._rec_manager.get_recording_file_context()
        except Exception:
            logger.exception("Failed to get finalized recording file context")
            final_file_context = {}

        context.update(final_file_context)
        return context

    def _notify_processor_recording_stopped(self) -> None:
        processor = self._get_dlc_processor_instance()
        if processor is None:
            return

        hook = getattr(processor, "on_recording_stopped", None)
        if not callable(hook):
            return

        try:
            context = self._final_processor_recording_context()
            hook(context)
            logger.info("Notified processor recording stopped")
        except Exception:
            logger.exception("Processor on_recording_stopped hook failed")

    def _finalize_processor_recording(self) -> None:
        """Notify the processor and save its recording data."""
        try:
            self._notify_processor_recording_stopped()
            self._save_processor_data_if_available()
        finally:
            self._processor_recording_context = None
            self._processor_recording_started_notified = False

    def _on_recording_stopped_async(self) -> None:
        if self._processor_recording_context is not None:
            self._finalize_processor_recording()

        self._recording_stopping = False
        self.start_record_button.setEnabled(True)
        self.stop_record_button.setEnabled(False)
        self.statusBar().showMessage("Multi-camera recording stopped", 3000)
        self._update_camera_controls_enabled()

    def _on_recording_stop_failed_async(self, message: str) -> None:
        self._recording_stopping = False

        still_active = self._rec_manager.is_active
        self.start_record_button.setEnabled(not still_active)
        self.stop_record_button.setEnabled(still_active)

        self.statusBar().showMessage(
            f"Failed to stop recording: {message}",
            10000,
        )
        self._update_camera_controls_enabled()

    # ------------------------------------------------------------------
    # Camera control
    def _show_logo_and_text(self):
        """Show the transparent logo with text below it in the preview area when not running."""

        size = self.video_label.size()

        if size.width() <= 0 or size.height() <= 0:
            return

        # Prepare blank canvas (transparent)
        composed = QPixmap(size)
        composed.fill(Qt.transparent)

        painter = QPainter(composed)
        painter.setRenderHint(QPainter.SmoothPixmapTransform)
        painter.setRenderHint(QPainter.Antialiasing)

        # --- Scale logo to at most 50% height (nice proportion) ---
        max_logo_height = int(size.height() * 0.45)
        logo = self._preview_pixmap.scaledToHeight(max_logo_height, Qt.SmoothTransformation)

        # Center the logo horizontally
        logo_x = (size.width() - logo.width()) // 2
        logo_y = int(size.height() * 0.15)  # small top margin

        painter.drawPixmap(logo_x, logo_y, logo)

        # --- Draw text BELOW the logo ---
        painter.setPen(QColor(255, 255, 255))
        painter.setFont(QFont("Arial", 22, QFont.Bold))

        text = "DeepLabCut-Live! "
        try:
            version = importlib.metadata.version("dlclivegui")
        except Exception:
            version = ""
        if version:
            text += f"\n(v{version})"

        # Position text under the logo with a small gap
        text_rect = QRect(
            0,
            logo_y + logo.height() + 15,  # 15px gap under logo
            size.width(),
            size.height() - (logo_y + logo.height() + 15),
        )

        painter.drawText(text_rect, Qt.AlignHCenter | Qt.AlignTop, text)

        painter.end()
        self.video_label.setPixmap(composed)

    def _start_preview(self) -> None:
        """Start camera preview - uses multi-camera controller for all configurations."""
        active_cams = self._config.multi_camera.get_active_cameras()
        if not active_cams:
            self._show_error("No cameras configured. Use 'Configure Cameras...' to add cameras.")
            return

        # Determine if we're in single or multi-camera mode
        self._multi_camera_mode = len(active_cams) > 1

        self.preview_button.setEnabled(False)
        self.stop_preview_button.setEnabled(True)
        self._current_frame = None
        self._raw_frame = None
        self._last_pose = None
        self._multi_camera_frames.clear()
        self._multi_camera_display_ids.clear()
        self._fps_tracker.clear()
        self._last_display_time = 0.0

        if hasattr(self, "camera_stats_label"):
            self.camera_stats_label.setText(f"Starting {len(active_cams)} camera(s)…")
        self.statusBar().showMessage(f"Starting preview ({len(active_cams)} camera(s))…", 3000)

        # Store active settings for single camera mode (for DLC, recording frame rate, etc.)
        self._active_camera_settings = active_cams[0] if active_cams else None
        for cam in active_cams:
            if not isinstance(cam.properties, dict):
                cam.properties = {}
            ns = cam.properties.setdefault((cam.backend or "").lower(), {})
            if isinstance(ns, dict):
                ns["fast_start"] = False

        self.multi_camera_controller.start(active_cams)
        self._update_inference_buttons()
        self._update_camera_controls_enabled()

    def _stop_preview(self) -> None:
        """Stop camera preview."""
        if not self.multi_camera_controller.is_active():
            return

        self.preview_button.setEnabled(False)
        self.stop_preview_button.setEnabled(False)
        self.start_inference_button.setEnabled(False)
        self.stop_inference_button.setEnabled(False)
        self.statusBar().showMessage("Stopping preview…", 3000)

        # Stop any active recording first
        self._stop_multi_camera_recording()

        self._pending_recording_after_preview = False
        self._stop_inference(show_message=False)
        self.multi_camera_controller.stop()
        self._fps_tracker.clear()
        self._last_display_time = 0.0
        if hasattr(self, "camera_stats_label"):
            self.camera_stats_label.setText("Camera idle")
        # self._show_logo_and_text()

    def _configure_dlc(self) -> bool:
        try:
            settings = self._dlc_settings_from_ui()
        except (
            ValueError,
            RuntimeError,
            json.JSONDecodeError,
        ) as exc:
            self._show_error(f"Invalid DLCLive settings: {exc}")
            return False

        if not settings.model_path:
            self._show_error("Please select a DLCLive model before starting inference.")
            return False

        processor = None
        processor_spec = None
        selected_key = self.processor_combo.currentData()

        self._settings_store.set_processor_key(selected_key)

        if self._custom_processor_enabled():
            try:
                processor_info = self._scanned_processors[selected_key]
                processor_class = processor_info["class"]
                processor_name = processor_info.get(
                    "name",
                    processor_class.__name__,
                )

                if processor_builds_in_worker(processor_class):
                    processor_spec = create_spec_from_scan(
                        self._scanned_processors,
                        selected_key,
                    )

                    log_processor_context(
                        f"MainWindow._configure_dlc - SPEC: {processor_class.__name__}",
                        logger,
                    )
                else:
                    processor = instantiate_from_scan(
                        self._scanned_processors,
                        selected_key,
                    )

                    log_processor_context(
                        f"MainWindow._configure_dlc - INSTANCE: {type(processor).__name__}",
                        logger,
                    )

                self.statusBar().showMessage(
                    f"Loaded processor: {processor_name}",
                    3000,
                )

            except Exception as exc:
                error_msg = f"Failed to configure processor: {exc}"
                self._show_error(error_msg)
                logger.exception(error_msg)
                return False

        elif selected_key is not None:
            self.statusBar().showMessage(
                f"Custom processor disabled: {selected_key}",
                3000,
            )

        self._dlc.configure(
            settings,
            processor=processor,
            processor_spec=processor_spec,
        )
        self._model_path_store.save_if_valid(settings.model_path)
        return True

    def _update_inference_buttons(self) -> None:
        preview_running = self.multi_camera_controller.is_running()
        self.start_inference_button.setEnabled(preview_running and not self._dlc_active)
        self.stop_inference_button.setEnabled(preview_running and self._dlc_active)

    def _update_dlc_controls_enabled(self) -> None:
        """Enable/disable DLC settings based on inference state."""
        allow_changes = not self._dlc_active

        widgets = [
            self.model_path_edit,
            self.browse_model_button,
            self.dlc_camera_combo,
        ]

        processor_widgets = [
            self.processor_folder_edit,
            self.browse_processor_folder_button,
            self.refresh_processors_button,
            self.processor_combo,
        ]

        for widget in widgets:
            widget.setEnabled(allow_changes)

        for widget in processor_widgets:
            widget.setEnabled(allow_changes)

        if hasattr(self, "use_custom_proc_checkbox"):
            self.use_custom_proc_checkbox.setEnabled(allow_changes)

    def _update_camera_controls_enabled(self) -> None:
        multi_cam_recording = self._rec_manager.is_active

        # Check if preview is running
        preview_running = self.multi_camera_controller.is_running()

        allow_changes = not preview_running and not self._dlc_active and not multi_cam_recording

        # Recording settings (codec, crf) should be editable when not recording
        recording_editable = not multi_cam_recording
        self.codec_combo.setEnabled(recording_editable)
        self.crf_spin.setEnabled(recording_editable)
        if hasattr(self, "fast_encoding_checkbox"):
            self.fast_encoding_checkbox.setEnabled(recording_editable)

        # Config cameras button should be available when not in preview/recording
        self.config_cameras_button.setEnabled(allow_changes)

        # Disable loading configurations when preview/recording is active
        if hasattr(self, "load_config_action"):
            self.load_config_action.setEnabled(allow_changes)

    def _display_frame(self, frame: np.ndarray, *, force: bool = False) -> None:
        if frame is None:
            return
        now = time.perf_counter()
        if not force and (now - self._last_display_time) < self._display_interval:
            return
        self._last_display_time = now
        self._update_video_display(frame)

    def _update_display_from_pending(self) -> None:
        """Update display from pending frames (called by display timer)."""
        if not self._display_dirty:
            return
        if not self._multi_camera_frames:
            return

        self._display_dirty = False

        # Create tiled frame on demand (moved from camera thread for performance)
        tiled = create_tiled_frame(self._multi_camera_frames, labels=self._multi_camera_display_ids)
        if tiled is not None:
            self._current_frame = tiled
            self._update_video_display(tiled)

    def _update_metrics(self) -> None:
        # --- Camera stats ---
        if hasattr(self, "camera_stats_label"):
            running = self.multi_camera_controller.is_running()
            if running:
                active_count = self.multi_camera_controller.get_active_count()

                # Build per-camera FPS list for active cameras only
                active_cams = self._config.multi_camera.get_active_cameras()
                lines = []
                for cam in active_cams:
                    cam_id = get_camera_id(cam)
                    display_id = get_display_id(cam)
                    fps = self._fps_tracker.fps(cam_id)
                    # Make a compact label: name [backend:index] @ fps
                    label = f"{display_id} [{cam.backend}:{cam.index}]"
                    if fps > 0:
                        lines.append(f"{label} @ {fps:.1f} fps")
                    else:
                        lines.append(f"{label} @ Measuring…")

                if active_count == 1:
                    # Single camera: show just the line
                    summary = lines[0] if lines else "Measuring…"
                else:
                    # Multi camera: join lines with separator
                    summary = " | ".join(lines)

                self.camera_stats_label.setText(summary)
            else:
                self.camera_stats_label.setText("Camera idle")

        # --- DLC processor stats ---
        if hasattr(self, "dlc_stats_label"):
            if self._dlc_active and self._dlc_initialized:
                stats = self._dlc.get_stats()
                summary = format_dlc_stats(stats)
                self.dlc_stats_label.setText(summary)
            else:
                self.dlc_stats_label.setText("DLC processor idle")

        # Update processor status (connection and recording state)
        if hasattr(self, "processor_status_label") and self._custom_processor_enabled():
            self._update_processor_status()

        # --- Recorder stats ---
        if hasattr(self, "recording_stats_label"):
            if self._rec_manager.is_active:
                summary = self._rec_manager.get_stats_summary()
                self._last_recorder_summary = summary
                self.recording_stats_label.setText(summary)
            else:
                self.recording_stats_label.setText(self._last_recorder_summary)

    def _update_processor_status(self) -> None:
        """Update processor connection and recording status, handle auto-recording."""
        if not self._custom_processor_enabled():
            self.processor_status_label.setText("Disabled")
            return

        if not self._dlc_active or not self._dlc_initialized:
            self.processor_status_label.setText("Not active")
            return

        # Get processor instance from _dlc
        processor = self._dlc._processor

        if processor is None:
            self.processor_status_label.setText("None loaded")
            return

        # Check if processor has the required attributes (socket-based processors)
        if not hasattr(processor, "conns") or not hasattr(processor, "_recording"):
            self.processor_status_label.setText("No status info")
            return

        # Get connection count and recording state
        num_clients = len(processor.conns)
        is_recording = processor.recording if hasattr(processor, "recording") else False

        # Format status message
        client_str = f"{num_clients} client{'s' if num_clients != 1 else ''}"
        recording_str = "Yes" if is_recording else "No"
        self.processor_status_label.setText(f"Clients: {client_str} | Recording: {recording_str}")

        # Handle auto-recording based on processor's video recording flag
        if hasattr(processor, "_vid_recording") and self.use_custom_proc_checkbox.isChecked():
            current_vid_recording = processor.video_recording

            # Check if video recording state changed
            if current_vid_recording != self._last_processor_vid_recording:
                if current_vid_recording:
                    # Start video recording
                    if not self._rec_manager.is_active:
                        # Get session name from processor
                        session_name = getattr(processor, "session_name", "auto_session")
                        self._auto_record_session_name = session_name

                        # Processor overrides session name field + persist it
                        self.session_name_edit.setText(session_name)
                        self._settings_store.set_session_name(session_name)

                        # Optional: set base filename to session name (readable stable filenames)
                        self.filename_edit.setText(session_name)
                        self._update_recording_path_preview()

                        self._start_recording()
                        self.statusBar().showMessage(f"Auto-started recording: {session_name}", 3000)
                        logger.info(f"Auto-recording started for session: {session_name}")
                else:
                    # Stop video recording
                    if self._rec_manager.is_active:
                        self._stop_recording()
                        self.statusBar().showMessage("Auto-stopped recording", 3000)
                        logger.info("Auto-recording stopped")

                self._last_processor_vid_recording = current_vid_recording

    def _start_inference(self) -> None:
        if self._dlc_active:
            self.statusBar().showMessage("Pose inference already running", 3000)
            return
        if not self.multi_camera_controller.is_running():
            self._show_error("Start the camera preview before running pose inference.")
            return
        if not self._configure_dlc():
            self._update_inference_buttons()
            return
        self._dlc.reset()
        self._last_pose = None
        self._dlc_active = True
        self._dlc_initialized = False

        # Update button to show initializing state
        self.start_inference_button.setText("Initializing DLCLive!")
        self.start_inference_button.setStyleSheet("background-color: #4A90E2; color: white;")
        self.start_inference_button.setEnabled(False)
        self.stop_inference_button.setEnabled(True)

        self.statusBar().showMessage("Initializing DLCLive…", 3000)
        self._update_camera_controls_enabled()
        self._update_dlc_controls_enabled()

    def _stop_inference(self, show_message: bool = True) -> None:
        if self._rec_manager.is_active:
            answer = QMessageBox.question(
                self,
                "Stop inference while recording?",
                "This will stop the currently running DLC-live custom processor, if any.\n"
                "File saving will not be handled via the standard 'recording stopped' event hooks"
                ", so data will only be saved if the processor handles saving on stop.\n\n"
                "Unsaved processor data may be lost or not be paired with the recording.\n\n"
                "Stop inference anyway?",
            )
            if answer != QMessageBox.Yes:
                return

        was_active = self._dlc_active
        self._dlc_active = False
        self._dlc_initialized = False
        # Does NOT invoke the normal rec-stop/save hooks. Persistence is processor-dependent.
        self._dlc.reset(reset_processor_plugin=True)
        self._last_pose = None
        self._last_processor_vid_recording = False
        self._auto_record_session_name = None

        # Reset button appearance
        self.start_inference_button.setText("Start pose inference")
        self.start_inference_button.setStyleSheet("")

        if self._current_frame is not None:
            self._display_frame(self._current_frame, force=True)
        if was_active and show_message:
            self.statusBar().showMessage("Pose inference stopped", 3000)
        self._update_inference_buttons()
        self._update_camera_controls_enabled()
        self._update_dlc_controls_enabled()

    # ------------------------------------------------------------------ recording
    def _start_recording(self) -> None:
        """Start recording from all active cameras."""
        # Auto-start preview if not running
        if not self.multi_camera_controller.is_running():
            active_cams = self._config.multi_camera.get_active_cameras()
            if not active_cams:
                self._show_error("No cameras configured. Use 'Configure Cameras...' to add cameras.")
                return

            self._pending_recording_after_preview = True
            self._start_preview()
            # Wait a moment for cameras to initialize before recording
            # The recording will start after preview is confirmed running
            self.statusBar().showMessage("Starting preview before recording...", 3000)
            # Use a single-shot timer to start recording after preview starts
            # QTimer.singleShot(500, self._start_multi_camera_recording)
            return

        # Preview already running, start recording immediately
        self._start_multi_camera_recording()

    def _try_start_pending_recording(self) -> None:
        if not self._pending_recording_after_preview:
            return

        if self._rec_manager.is_active:
            self._pending_recording_after_preview = False
            return

        if not self.multi_camera_controller.is_running():
            return

        active_cams = self._config.multi_camera.get_active_cameras()
        expected_ids = {get_camera_id(cam) for cam in active_cams}

        if not expected_ids:
            self._pending_recording_after_preview = False
            return

        available_ids = set(self._multi_camera_frames.keys())

        if not expected_ids.issubset(available_ids):
            return

        self._pending_recording_after_preview = False
        self._start_multi_camera_recording()

    def _stop_recording(self) -> None:
        """Stop recording from all cameras."""
        self._stop_multi_camera_recording()

    def _on_pose_ready(self, result: PoseResult) -> None:
        if not self._dlc_active:
            return

        with self._dlc_timing.measure("DLC.pose_ready_callback"):
            self._last_pose = result

            # try:
            #     latency_ms = (time.time() - float(result.timestamp)) * 1000.0
            #      if logger.isEnabledFor(logging.DEBUG):
            #          logger.debug("DLC pose latency camera_timestamp_to_gui=%.2f ms", latency_ms)
            # except Exception:
            #     pass

            if self._current_frame is not None:
                self._display_dirty = True
                # with self._dlc_timing.measure("DLC.display_after_pose"):
                # self._display_frame(self._current_frame, force=True)

        self._dlc_timing.maybe_log()

    def _on_dlc_error(self, message: str) -> None:
        self._stop_inference(show_message=False)
        self._show_error(message)

    def _update_video_display(self, frame: np.ndarray) -> None:
        display_frame = frame

        if self.show_predictions_checkbox.isChecked() and self._last_pose and self._last_pose.pose is not None:
            display_frame = draw_pose(
                frame,
                self._last_pose.pose,
                p_cutoff=self._p_cutoff,
                colormap=self._colormap,
                offset=self._dlc_tile_offset,
                scale=self._dlc_tile_scale,
            )

        if self._bbox_enabled:
            display_frame = draw_bbox(
                display_frame,
                (self._bbox_x0, self._bbox_y0, self._bbox_x1, self._bbox_y1),
                color_bgr=self._bbox_color,
                offset=self._dlc_tile_offset,
                scale=self._dlc_tile_scale,
            )

        rgb = cv2.cvtColor(display_frame, cv2.COLOR_BGR2RGB)

        h, w, ch = rgb.shape
        bytes_per_line = ch * w
        image = QImage(rgb.data, w, h, bytes_per_line, QImage.Format.Format_RGB888)
        pixmap = QPixmap.fromImage(image)

        # Scale pixmap to fit label while preserving aspect ratio
        scaled_pixmap = pixmap.scaled(
            self.video_label.size(), Qt.AspectRatioMode.KeepAspectRatio, Qt.TransformationMode.SmoothTransformation
        )
        self.video_label.setPixmap(scaled_pixmap)

    def _on_show_predictions_changed(self, _state: int) -> None:
        if self._current_frame is not None:
            self._display_frame(self._current_frame, force=True)

    def _on_bbox_changed(self, _value: int = 0) -> None:
        """Handle bounding box parameter changes."""
        self._bbox_enabled = self.bbox_enabled_checkbox.isChecked()
        self._bbox_x0 = self.bbox_x0_spin.value()
        self._bbox_y0 = self.bbox_y0_spin.value()
        self._bbox_x1 = self.bbox_x1_spin.value()
        self._bbox_y1 = self.bbox_y1_spin.value()

        # Force redraw if preview is running
        if self._current_frame is not None:
            self._display_frame(self._current_frame, force=True)

    def _on_dlc_initialised(self, success: bool) -> None:
        if success:
            self._dlc_initialized = True
            if self._processor_recording_context is not None and not self._processor_recording_started_notified:
                self._notify_processor_recording_started(self._processor_recording_context)

            # Update button to show running state
            self.start_inference_button.setText("DLCLive running!")
            self.start_inference_button.setStyleSheet("background-color: #4CAF50; color: white;")
            self.statusBar().showMessage("DLCLive initialized successfully", 3000)
        else:
            self._dlc_initialized = False
            # Reset button on failure
            self.start_inference_button.setText("Start pose inference")
            self.start_inference_button.setStyleSheet("")
            self.statusBar().showMessage("DLCLive initialization failed", 5000)
            # Stop inference since initialization failed
            self._stop_inference(show_message=False)

    # ------------------------------------------------------------------
    # Helpers
    def _show_error(self, message: str) -> None:
        self.statusBar().showMessage(message, 5000)
        QMessageBox.critical(self, "Error", message)

    def _show_warning(self, message: str) -> None:
        """Display a warning message dialog."""
        self.statusBar().showMessage(f"⚠ {message}", 5000)
        QMessageBox.warning(self, "Warning", message)

    def _show_info(self, message: str) -> None:
        """Display an informational message dialog."""
        self.statusBar().showMessage(message, 5000)
        QMessageBox.information(self, "Information", message)

    def _populate_bbox_color_combo_with_swatches(self):
        self.bbox_color_combo.clear()
        for enum_item in BBoxColors:
            bgr = enum_item.value
            name = enum_item.name.title()
            pix = QPixmap(40, 16)
            pix.fill(Qt.transparent)
            p = QPainter(pix)
            p.fillRect(0, 0, 40, 16, Qt.black)  # border/background
            p.fillRect(1, 1, 38, 14, Qt.white)  # inner bg
            # Convert BGR to RGB for QPainter/QColor
            rgb = (bgr[2], bgr[1], bgr[0])
            p.fillRect(2, 2, 36, 12, QColor(*rgb))
            p.end()
            self.bbox_color_combo.addItem(QIcon(pix), name, enum_item)

    def _set_combo_from_color(self, bgr: tuple[int, int, int]) -> None:
        # Find combo entry whose enum value matches bgr
        for i in range(self.bbox_color_combo.count()):
            enum_item = self.bbox_color_combo.itemData(i)
            if enum_item is not None and getattr(enum_item, "value", None) == bgr:
                self.bbox_color_combo.setCurrentIndex(i)
                return

    # ------------------------------------------------------------------
    # Qt overrides
    def closeEvent(self, event: QCloseEvent) -> None:  # pragma: no cover - GUI behaviour
        if self.multi_camera_controller.is_running():
            self.multi_camera_controller.stop(wait=True)

        if hasattr(self, "_camera_validation_timer") and self._camera_validation_timer.isActive():
            self._camera_validation_timer.stop()
        # Stop all multi-camera recorders
        try:
            self.multi_camera_controller.set_recording_frame_is_enabled(False)
        except Exception:
            logger.exception("Failed to disable recording frame emission during shutdown")

        while not self._rec_manager.stop_all():
            logger.info("Retrying recorder stop during shutdown...")
            time.sleep(RECORD_STOP_RETRY_INTERVAL)
        if self._processor_recording_context is not None:
            self._finalize_processor_recording()

        # Close the camera dialog if open (ensures its worker thread is canceled)
        if getattr(self, "_cam_dialog", None) is not None and self._cam_dialog.isVisible():
            try:
                self._cam_dialog.close()
            except Exception:
                pass
            self._cam_dialog = None

        self._dlc.shutdown()
        if hasattr(self, "_metrics_timer"):
            self._metrics_timer.stop()

        if hasattr(self, "_display_timer"):
            self._display_timer.stop()

        # Remember model path on exit
        self._model_path_store.save_if_valid(self.model_path_edit.text().strip())

        # Remember processor folder on exit
        if hasattr(self, "processor_folder_edit"):
            self._settings_store.set_processor_folder(self.processor_folder_edit.text().strip())

        # Remember user-preferred inference camera on exit.
        if hasattr(self, "_inference_camera_id"):
            self._settings_store.set_inference_camera_id(self._inference_camera_id)

        # Remember selected processor on exit
        if hasattr(self, "processor_combo"):
            self._settings_store.set_processor_key(self.processor_combo.currentData())

        # Remember processor-control checkbox state on exit
        if hasattr(self, "use_custom_proc_checkbox"):
            self._settings_store.set_processor_control_enabled(self._custom_processor_enabled())

        if hasattr(self, "filename_edit"):
            self._settings_store.set_rec_filename(self.filename_edit.text().strip())

        # Flush QSettings best-effort
        try:
            self.settings.sync()
        except Exception:
            logger.exception("Failed to sync QSettings on close", exc_info=True)

        # Close the window
        super().closeEvent(event)