framesource 0.3.0__py3-none-any.whl

framesource/sources/folder_capture.py

@@ -0,0 +1,920 @@
+import logging
+import os
+import time
+import warnings
+from typing import Any, Optional
+
+import cv2
+import numpy as np
+
+from .video_capture_base import VideoCaptureBase
+
+# Try to import watchdog for folder monitoring. These are re-imported locally
+# where used (see below); this pair only probes availability.
+try:
+    from watchdog.events import FileSystemEventHandler  # noqa: F401
+    from watchdog.observers import Observer  # noqa: F401
+
+    WATCHDOG_AVAILABLE = True
+except ImportError:
+    WATCHDOG_AVAILABLE = False
+    logging.getLogger(__name__).warning(
+        "watchdog library not available. Install with 'pip install watchdog' "
+        "for automatic folder monitoring."
+    )
+
+logger = logging.getLogger(__name__)
+
+
+class FolderWatcherHandler:
+    """File system event handler for folder watching."""
+
+    def __init__(self, folder_capture_instance):
+        self.folder_capture = folder_capture_instance
+        self.valid_exts = (".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".tif")
+
+    def on_created(self, event):
+        """Handle file creation events."""
+        if not event.is_directory and self._is_image_file(event.src_path):
+            logger.info(f"New image file detected: {event.src_path}")
+            self._add_file(event.src_path)
+
+    def on_deleted(self, event):
+        """Handle file deletion events."""
+        if not event.is_directory and self._is_image_file(event.src_path):
+            logger.info(f"Image file deleted: {event.src_path}")
+            self._remove_file(event.src_path)
+
+    def on_moved(self, event):
+        """Handle file move/rename events."""
+        if not event.is_directory:
+            src_is_image = self._is_image_file(event.src_path)
+            dest_is_image = self._is_image_file(event.dest_path)
+
+            if src_is_image and dest_is_image:
+                # Image renamed to another image
+                logger.info(f"Image file renamed: {event.src_path} -> {event.dest_path}")
+                self._rename_file(event.src_path, event.dest_path)
+            elif src_is_image:
+                # Image renamed to non-image (effectively deleted)
+                logger.info(f"Image file removed: {event.src_path}")
+                self._remove_file(event.src_path)
+            elif dest_is_image:
+                # Non-image renamed to image (effectively added)
+                logger.info(f"Image file added: {event.dest_path}")
+                self._add_file(event.dest_path)
+
+    def _is_image_file(self, file_path):
+        """Check if file is an image based on extension."""
+        return file_path.lower().endswith(self.valid_exts)
+
+    def _add_file(self, file_path):
+        """Add a new file to the list immediately."""
+        if file_path not in self.folder_capture.image_files:
+            self.folder_capture.image_files.append(file_path)
+            # Re-sort the list according to the current sorting preference
+            if self.folder_capture.sort_by == "date":
+                self.folder_capture.image_files.sort(
+                    key=lambda x: os.path.getctime(x) if os.path.exists(x) else 0
+                )
+            else:
+                self.folder_capture.image_files.sort()
+
+            self.folder_capture._last_file_count = len(self.folder_capture.image_files)
+            logger.info(
+                f"Added file to list: {file_path} (total: {len(self.folder_capture.image_files)})"
+            )
+
+    def _remove_file(self, file_path):
+        """Remove a file from the list immediately."""
+        if file_path in self.folder_capture.image_files:
+            # Store current position before removal
+            current_index = self.folder_capture.index - 1 if self.folder_capture.index > 0 else 0
+            was_current_file = (
+                current_index < len(self.folder_capture.image_files)
+                and self.folder_capture.image_files[current_index] == file_path
+            )
+
+            # Get the index of the file to be removed before removing it
+            removed_index = self.folder_capture.image_files.index(file_path)
+
+            self.folder_capture.image_files.remove(file_path)
+            self.folder_capture._last_file_count = len(self.folder_capture.image_files)
+
+            # Adjust index if the removed file was at or before current position
+            if removed_index <= current_index:
+                if was_current_file:
+                    # Current file was removed, stay at same index (will get next file)
+                    pass
+                else:
+                    # File before current was removed, adjust index
+                    self.folder_capture.index = max(0, self.folder_capture.index - 1)
+
+            # Ensure index is within bounds
+            if self.folder_capture.index >= len(self.folder_capture.image_files):
+                self.folder_capture.index = max(0, len(self.folder_capture.image_files) - 1)
+
+            logger.info(
+                f"Removed file from list: {file_path} "
+                f"(total: {len(self.folder_capture.image_files)})"
+            )
+
+    def _rename_file(self, old_path, new_path):
+        """Update file path when a file is renamed."""
+        if old_path in self.folder_capture.image_files:
+            index = self.folder_capture.image_files.index(old_path)
+            self.folder_capture.image_files[index] = new_path
+
+            # Re-sort if necessary
+            if self.folder_capture.sort_by == "date":
+                self.folder_capture.image_files.sort(
+                    key=lambda x: os.path.getctime(x) if os.path.exists(x) else 0
+                )
+            else:
+                self.folder_capture.image_files.sort()
+
+            logger.info(f"Renamed file in list: {old_path} -> {new_path}")
+
+
+class FolderCapture(VideoCaptureBase):
+    """
+    Capture class for reading images from a folder as a video stream.
+    Images can be sorted by creation time or by name.
+    Supports automatic folder monitoring to detect new/removed images.
+    """
+
+    has_discovery = False  # Uses folder paths, not discoverable devices
+    supports_exposure = False  # Still images have no controllable exposure
+    supports_gain = False  # Still images have no controllable gain
+
+    def __init__(
+        self,
+        source: str,
+        sort_by: str = "name",
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        fps: float = 30.0,
+        real_time: bool = True,
+        loop: bool = False,
+        watch_folder: bool = True,
+        **kwargs,
+    ):
+        """Initialize the folder (image sequence) capture.
+
+        Args:
+            source: Path to the folder containing image files.
+            sort_by: ``'name'`` (default) or ``'date'`` ordering of images.
+            width: Optional target frame width (images are resized when both
+                ``width`` and ``height`` are set).
+            height: Optional target frame height (see ``width``).
+            fps: Playback frame rate in frames per second.
+            real_time: Play at ``fps`` (disable for fastest processing).
+            loop: Restart from the first image when the end is reached.
+            watch_folder: Monitor the folder for added/removed files (requires
+                the optional ``watchdog`` dependency).
+            **kwargs: Additional passthrough options stored on ``self.config``.
+        """
+        super().__init__(source, **kwargs)
+        self.sort_by = sort_by
+        self.width = width
+        self.height = height
+        self.fps = fps
+        self.real_time = real_time
+        self.loop = loop
+        self.watch_folder = watch_folder and WATCHDOG_AVAILABLE
+        self.image_files: list[str] = []
+        self.index = 0
+        self.time_of_last_frame = 0.0
+        self._capture_thread = None
+        self._stop_event = None
+        self._latest_frame = None
+        self._latest_success = False
+
+        # Folder watching components
+        self._folder_observer = None
+        self._folder_handler = None
+        self._refresh_lock = None
+        self._last_file_count = 0
+
+        if not WATCHDOG_AVAILABLE and watch_folder:
+            logger.warning(
+                "Folder watching requested but watchdog library not available. "
+                "Install with 'pip install watchdog'."
+            )
+
+    def _start_folder_watching(self):
+        """Start monitoring the folder for file changes."""
+        if not self.watch_folder or not WATCHDOG_AVAILABLE:
+            return
+
+        try:
+            import threading
+
+            self._refresh_lock = threading.Lock()
+
+            # Create and configure the folder watcher
+            if WATCHDOG_AVAILABLE:
+                from watchdog.events import FileSystemEventHandler
+                from watchdog.observers import Observer
+
+                class WatchdogHandler(FileSystemEventHandler):
+                    def __init__(self, folder_handler):
+                        self.folder_handler = folder_handler
+
+                    def on_created(self, event):
+                        self.folder_handler.on_created(event)
+
+                    def on_deleted(self, event):
+                        self.folder_handler.on_deleted(event)
+
+                    def on_moved(self, event):
+                        self.folder_handler.on_moved(event)
+
+                self._folder_handler = FolderWatcherHandler(self)
+                watchdog_handler = WatchdogHandler(self._folder_handler)
+
+                self._folder_observer = Observer()
+                self._folder_observer.schedule(watchdog_handler, self.source, recursive=False)
+                self._folder_observer.start()
+
+                logger.info(f"Started folder watching for: {self.source}")
+        except Exception as e:
+            logger.error(f"Failed to start folder watching: {e}")
+            self._folder_observer = None
+
+    def _stop_folder_watching(self):
+        """Stop monitoring the folder for file changes."""
+        if self._folder_observer:
+            try:
+                self._folder_observer.stop()
+                self._folder_observer.join(timeout=2)
+                logger.info("Stopped folder watching")
+            except Exception as e:
+                logger.error(f"Error stopping folder watcher: {e}")
+            finally:
+                self._folder_observer = None
+                self._folder_handler = None
+
+    def _refresh_file_list_async(self):
+        """Async version of refresh_file_list to avoid blocking the file watcher."""
+        if hasattr(self, "_refresh_lock") and self._refresh_lock:
+            with self._refresh_lock:
+                self._refresh_file_list()
+        else:
+            self._refresh_file_list()
+
+    def connect(self) -> bool:
+        if not os.path.isdir(self.source):
+            logger.error(f"Folder not found: {self.source}")
+            return False
+        # List image files
+        valid_exts = (".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".tif")
+        files = [
+            os.path.join(self.source, f)
+            for f in os.listdir(self.source)
+            if f.lower().endswith(valid_exts)
+        ]
+        if self.sort_by == "date":
+            files.sort(key=lambda x: os.path.getctime(x))
+        else:
+            files.sort()  # Default: sort by name
+        if not files:
+            logger.error(f"No image files found in folder: {self.source}")
+            return False
+        self.image_files = files
+        self.index = 0
+        self.is_connected = True
+        self.time_of_last_frame = time.time()
+        self._last_file_count = len(files)  # Initialize file count tracking
+
+        # Start folder watching if enabled
+        self._start_folder_watching()
+
+        watch_state = "enabled" if self.watch_folder else "disabled"
+        logger.info(f"Connected to folder with {len(files)} images. Folder watching: {watch_state}")
+        return True
+
+    def disconnect(self) -> bool:
+        # Stop folder watching first
+        self._stop_folder_watching()
+
+        self.is_connected = False
+        self.image_files = []
+        self.index = 0
+        logger.info("Disconnected from folder capture.")
+        return True
+
+    def _refresh_file_list(self) -> bool:
+        """
+        Refresh the file list to handle files that may have been added, removed, or renamed.
+
+        Returns:
+            bool: True if file list was successfully refreshed
+        """
+        if not os.path.isdir(self.source):
+            logger.error(f"Source folder no longer exists: {self.source}")
+            return False
+
+        # Store current file path WITHOUT calling get_current_file_path() to avoid recursion
+        current_file = None
+        if self.image_files and 0 <= self.index - 1 < len(self.image_files):
+            current_file = (
+                self.image_files[self.index - 1] if self.index > 0 else self.image_files[0]
+            )
+
+        # Re-scan folder for image files
+        valid_exts = (".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".tif")
+        files = [
+            os.path.join(self.source, f)
+            for f in os.listdir(self.source)
+            if f.lower().endswith(valid_exts) and os.path.exists(os.path.join(self.source, f))
+        ]
+
+        if self.sort_by == "date":
+            files.sort(key=lambda x: os.path.getctime(x))
+        else:
+            files.sort()  # Default: sort by name
+
+        if not files:
+            logger.warning(f"No image files found in folder after refresh: {self.source}")
+            self.image_files = []
+            self.index = 0
+            return False
+
+        # Update file list
+        old_count = len(self.image_files)
+        self.image_files = files
+        new_count = len(self.image_files)
+
+        # Update the background monitor's file count tracking
+        self._last_file_count = new_count
+
+        # Try to maintain current position if the file still exists
+        if current_file and current_file in self.image_files:
+            self.index = (
+                self.image_files.index(current_file) + 1
+            )  # +1 because index is incremented after reading
+        else:
+            # File no longer exists, clamp index to valid range
+            self.index = min(self.index, len(self.image_files))
+            if self.index <= 0:
+                self.index = 0
+
+        logger.info(
+            f"Refreshed file list: {old_count} -> {new_count} files, current index: {self.index}"
+        )
+        return True
+
+    def _read_implementation(self) -> tuple[bool, Optional[np.ndarray]]:
+        if not self.is_connected or not self.image_files:
+            return False, None
+        # Real-time playback control
+        if self.real_time and self.fps > 0:
+            frame_duration = 1.0 / self.fps
+            now = time.time()
+            elapsed = now - self.time_of_last_frame
+            if elapsed < frame_duration:
+                time.sleep(frame_duration - elapsed)
+            self.time_of_last_frame = time.time()
+        # Read image
+        if self.index >= len(self.image_files):
+            if self.loop:
+                self.index = 0
+            else:
+                return False, None
+        img_path = self.image_files[self.index]
+
+        # Check if file still exists before trying to read it
+        if not os.path.exists(img_path):
+            logger.warning(f"Image file no longer exists: {img_path}")
+            # Try to refresh the file list to see if files were moved/renamed
+            self._refresh_file_list()
+            # Skip this file and try the next one
+            self.index += 1
+            return False, None
+
+        img = cv2.imread(img_path)
+        if img is None:
+            logger.warning(f"Failed to read image: {img_path}")
+            self.index += 1
+            return False, None
+        # Resize if needed
+        if self.width is not None and self.height is not None:
+            img = cv2.resize(img, (self.width, self.height), interpolation=cv2.INTER_AREA)
+        self.index += 1
+        return True, img
+
+    def set_exposure(self, value: float) -> bool:
+        logger.warning("Exposure control not applicable for folder capture.")
+        return False
+
+    def get_exposure(self) -> Optional[float]:
+        logger.warning("Exposure control not applicable for folder capture.")
+        return None
+
+    def set_gain(self, value: float) -> bool:
+        logger.warning("Gain control not applicable for folder capture.")
+        return False
+
+    def get_gain(self) -> Optional[float]:
+        logger.warning("Gain control not applicable for folder capture.")
+        return None
+
+    def enable_auto_exposure(self, enable: bool = True) -> bool:
+        logger.warning("Auto exposure control not applicable for folder capture.")
+        return False
+
+    def get_frame_size(self) -> Optional[tuple[int, int]]:
+        if not self.image_files:
+            return None
+
+        # Find the first existing image file
+        for img_path in self.image_files:
+            if os.path.exists(img_path):
+                img = cv2.imread(img_path)
+                if img is not None:
+                    h, w = img.shape[:2]
+                    if self.width is not None and self.height is not None:
+                        return (self.width, self.height)
+                    return (w, h)
+
+        # If no valid images found, try refreshing the file list
+        logger.warning("No valid image files found for frame size detection")
+        if self._refresh_file_list() and self.image_files:
+            # Try again with refreshed list
+            for img_path in self.image_files:
+                if os.path.exists(img_path):
+                    img = cv2.imread(img_path)
+                    if img is not None:
+                        h, w = img.shape[:2]
+                        if self.width is not None and self.height is not None:
+                            return (self.width, self.height)
+                        return (w, h)
+
+        return None
+
+    def set_frame_size(self, width: int, height: int) -> bool:
+        self.width = width
+        self.height = height
+        return True
+
+    def get_fps(self) -> Optional[float]:
+        return self.fps
+
+    def set_fps(self, fps: float) -> bool:
+        self.fps = fps
+        return True
+
+    def get_current_file_path(self) -> Optional[str]:
+        """
+        Get the file path of the current image.
+
+        Returns:
+            Optional[str]: Path to the current image file, or None if no current file
+        """
+        if not self.is_connected or not self.image_files:
+            return None
+
+        # Get the current index (accounting for the fact that index is incremented after reading)
+        current_index = self.index - 1 if self.index > 0 else 0
+
+        # Handle case where we've reached the end and looping is disabled
+        if current_index >= len(self.image_files):
+            if self.loop:
+                current_index = 0
+            else:
+                # Return the last valid file path
+                current_index = len(self.image_files) - 1
+
+        # Ensure index is within bounds
+        if 0 <= current_index < len(self.image_files):
+            file_path = self.image_files[current_index]
+            # Check if file still exists
+            if os.path.exists(file_path):
+                return file_path
+            else:
+                logger.warning(f"Current file no longer exists: {file_path}")
+                # Try to refresh file list
+                if self._refresh_file_list():
+                    # Retry with refreshed list
+                    if 0 <= current_index < len(self.image_files):
+                        return self.image_files[current_index]
+
+        return None
+
+    def get_current_file_info(self) -> Optional[dict]:
+        """
+        Get detailed information about the current image file.
+
+        Returns:
+            Optional[dict]: Dictionary containing file information, or None if no current file
+        """
+        current_path = self.get_current_file_path()
+        if current_path is None:
+            return None
+
+        try:
+            file_stat = os.stat(current_path)
+            return {
+                "path": current_path,
+                "filename": os.path.basename(current_path),
+                "size_bytes": file_stat.st_size,
+                "creation_time": file_stat.st_ctime,
+                "modification_time": file_stat.st_mtime,
+                "index": self.index - 1 if self.index > 0 else 0,
+                "total_files": len(self.image_files),
+            }
+        except OSError as e:
+            logger.warning(f"Could not get file info for {current_path}: {e}")
+            return None
+
+    def get_file_list(self) -> list[str]:
+        """
+        Get the complete list of image files in the folder.
+
+        Returns:
+            List[str]: List of all image file paths
+        """
+        return self.image_files.copy()
+
+    def get_current_index(self) -> int:
+        """
+        Get the current file index.
+
+        Returns:
+            int: Current index in the file list
+        """
+        return self.index - 1 if self.index > 0 else 0
+
+    def set_current_index(self, index: int) -> bool:
+        """
+        Set the current file index to jump to a specific image.
+
+        Args:
+            index: Index to jump to (0-based)
+
+        Returns:
+            bool: True if index was set successfully
+        """
+        if not self.is_connected or not self.image_files:
+            return False
+
+        if 0 <= index < len(self.image_files):
+            # Check if the target file exists
+            target_file = self.image_files[index]
+            if os.path.exists(target_file):
+                self.index = index
+                return True
+            else:
+                logger.warning(f"Target file at index {index} no longer exists: {target_file}")
+                # Try refreshing file list
+                if self._refresh_file_list():
+                    # Check if index is still valid after refresh
+                    if 0 <= index < len(self.image_files):
+                        self.index = index
+                        return True
+                return False
+        else:
+            logger.warning(f"Index {index} out of range (0-{len(self.image_files) - 1})")
+            return False
+
+    def validate_file_list(self) -> int:
+        """
+        Validate all files in the list and remove any that no longer exist.
+
+        Returns:
+            int: Number of files removed
+        """
+        if not self.image_files:
+            return 0
+
+        original_count = len(self.image_files)
+        current_file = self.get_current_file_path()
+
+        # Filter out files that no longer exist
+        valid_files = [f for f in self.image_files if os.path.exists(f)]
+
+        removed_count = original_count - len(valid_files)
+
+        if removed_count > 0:
+            logger.warning(f"Removed {removed_count} missing files from list")
+            self.image_files = valid_files
+
+            # Adjust current index
+            if current_file and current_file in self.image_files:
+                self.index = self.image_files.index(current_file)
+            else:
+                # Current file was removed, clamp index
+                self.index = min(self.index, len(self.image_files) - 1)
+                if self.index < 0:
+                    self.index = 0
+
+        return removed_count
+
+    def get_missing_files(self) -> list[str]:
+        """
+        Get a list of files that are in the file list but no longer exist on disk.
+
+        Returns:
+            List[str]: List of missing file paths
+        """
+        return [f for f in self.image_files if not os.path.exists(f)]
+
+    def enable_folder_watching(self, enable: bool = True) -> bool:
+        """
+        Enable or disable folder watching.
+
+        Args:
+            enable: True to enable, False to disable
+
+        Returns:
+            bool: True if successful
+        """
+        if not WATCHDOG_AVAILABLE:
+            logger.warning("Folder watching not available - watchdog library not installed")
+            return False
+
+        if enable and not self.watch_folder:
+            self.watch_folder = True
+            if self.is_connected:
+                self._start_folder_watching()
+            return True
+        elif not enable and self.watch_folder:
+            self.watch_folder = False
+            self._stop_folder_watching()
+            return True
+
+        return True  # Already in desired state
+
+    def is_folder_watching_enabled(self) -> bool:
+        """
+        Check if folder watching is currently enabled.
+
+        Returns:
+            bool: True if folder watching is enabled
+        """
+        return self.watch_folder and self._folder_observer is not None
+
+    def get_folder_watching_status(self) -> dict:
+        """
+        Get detailed folder watching status.
+
+        Returns:
+            dict: Status information
+        """
+        return {
+            "watchdog_available": WATCHDOG_AVAILABLE,
+            "watching_enabled": self.watch_folder,
+            "observer_running": self._folder_observer is not None
+            and self._folder_observer.is_alive()
+            if self._folder_observer
+            else False,
+            "folder_path": self.source,
+            "total_files": len(self.image_files),
+            "missing_files": len(self.get_missing_files()),
+        }
+
+    def force_refresh(self) -> int:
+        """
+        Manually trigger a file list refresh.
+
+        Returns:
+            int: Number of files in the updated list
+        """
+        self._refresh_file_list()
+        return len(self.image_files)
+
+    @classmethod
+    def discover(cls) -> list:
+        """
+        Discover method for folder capture sources.
+
+        Returns:
+            list: Empty list, as discovery is not applicable for folder-based sources.
+                Use this class directly with folder paths as the source parameter.
+        """
+        # Folder capture doesn't discover devices - it works with folder paths
+        logger.info("FolderCapture uses folder paths as sources, not discoverable devices.")
+        return []
+
+    @classmethod
+    def get_config_schema(cls) -> dict[str, Any]:
+        """Get configuration schema for folder capture"""
+        warnings.warn(
+            "get_config_schema() is deprecated and will be removed in a future release; "
+            "UI form schemas belong in the consuming application.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return {
+            "title": "Folder Capture Configuration",
+            "description": "Configure image folder as video stream settings",
+            "fields": [
+                {
+                    "name": "source",
+                    "label": "Folder Path",
+                    "type": "text",
+                    "placeholder": "path/to/image/folder",
+                    "description": "Path to folder containing image files",
+                    "required": True,
+                },
+                {
+                    "name": "sort_by",
+                    "label": "Sort Method",
+                    "type": "select",
+                    "options": [
+                        {"value": "name", "label": "By Name"},
+                        {"value": "date", "label": "By Creation Date"},
+                    ],
+                    "description": "How to sort images in the folder",
+                    "required": False,
+                    "default": "name",
+                },
+                {
+                    "name": "fps",
+                    "label": "Frame Rate (FPS)",
+                    "type": "number",
+                    "min": 1,
+                    "max": 120,
+                    "placeholder": "30",
+                    "description": "Frames per second for playback",
+                    "required": False,
+                    "default": 30,
+                },
+                {
+                    "name": "loop",
+                    "label": "Loop Playback",
+                    "type": "checkbox",
+                    "description": "Restart from first image when reaching the end",
+                    "required": False,
+                    "default": False,
+                },
+                {
+                    "name": "real_time",
+                    "label": "Real-time Playback",
+                    "type": "checkbox",
+                    "description": "Play at specified frame rate (disable for fastest processing)",
+                    "required": False,
+                    "default": True,
+                },
+                {
+                    "name": "watch_folder",
+                    "label": "Watch for Changes",
+                    "type": "checkbox",
+                    "description": "Automatically detect when files are added/removed",
+                    "required": False,
+                    "default": True,
+                },
+                {
+                    "name": "width",
+                    "label": "Width",
+                    "type": "number",
+                    "min": 160,
+                    "max": 4096,
+                    "placeholder": "original",
+                    "description": "Resize frame width (optional)",
+                    "required": False,
+                },
+                {
+                    "name": "height",
+                    "label": "Height",
+                    "type": "number",
+                    "min": 120,
+                    "max": 2160,
+                    "placeholder": "original",
+                    "description": "Resize frame height (optional)",
+                    "required": False,
+                },
+            ],
+        }
+
+
+# Standalone test code
+def _test_folder_capture():
+    import sys
+
+    # Use command line argument for folder path, or default to a test folder
+    if len(sys.argv) > 1:
+        folder = sys.argv[1]
+    else:
+        # Try some common test folders
+        test_folders = [
+            "C:/Users/olive/OneDrive/Desktop/image_folder",
+            "./media/image_seq",  # Relative to project root
+            "../media/image_seq",  # If running from frame_source directory
+            "../../media/image_seq",  # If running from deeper nested folder
+            "./test_images",
+            "../test_images",
+        ]
+
+        folder = None
+        for test_folder in test_folders:
+            if os.path.exists(test_folder) and os.path.isdir(test_folder):
+                folder = test_folder
+                break
+
+        if folder is None:
+            print("No test folder found. Usage: python folder_capture.py <folder_path>")
+            print(f"Tried folders: {test_folders}")
+            sys.exit(1)
+
+    print(f"Testing FolderCapture with folder: {folder}")
+
+    cap = FolderCapture(
+        folder, sort_by="date", fps=10, real_time=True, loop=True, watch_folder=True
+    )
+    if cap.connect():
+        print(f"Connected successfully! Found {len(cap.get_file_list())} image files.")
+
+        # Show folder watching status
+        watch_status = cap.get_folder_watching_status()
+        print(f"Folder watching status: {watch_status}")
+
+        # cap.start()
+        cv2.namedWindow("FolderCapture", cv2.WINDOW_NORMAL)
+        frame_count = 0
+        last_validation_time = time.time()
+        last_file_count = len(cap.get_file_list())
+
+        # Check for missing files initially
+        missing_files = cap.get_missing_files()
+        if missing_files:
+            print(f"Warning: {len(missing_files)} files are missing from the start")
+
+        print(
+            "Press 'q' to quit, 's' to skip to next image, 'r' to refresh file list, "
+            "'w' to toggle folder watching"
+        )
+
+        while cap.is_connected:
+            ret, frame = cap.read()
+            if ret:
+                frame_count += 1
+                if frame is not None:
+                    # Display current file information
+                    current_file = cap.get_current_file_path()
+                    file_info = cap.get_current_file_info()
+
+                    if current_file:
+                        print(f"Frame {frame_count}: {os.path.basename(current_file)}")
+                        if file_info:
+                            print(f"  Index: {file_info['index']}/{file_info['total_files'] - 1}")
+                            print(f"  Size: {file_info['size_bytes']} bytes")
+
+                    # Check if file count changed (new files detected)
+                    current_file_count = len(cap.get_file_list())
+                    if current_file_count != last_file_count:
+                        print(f"File count changed: {last_file_count} -> {current_file_count}")
+                        last_file_count = current_file_count
+
+                    # Periodically validate file list (every 30 seconds)
+                    current_time = time.time()
+                    if current_time - last_validation_time > 30:
+                        removed_count = cap.validate_file_list()
+                        if removed_count > 0:
+                            print(f"Validation: Removed {removed_count} missing files")
+                        last_validation_time = current_time
+
+                    cv2.imshow("FolderCapture", frame)
+
+                # Handle key presses
+                key = cv2.waitKey(1) & 0xFF
+                if key == ord("q"):
+                    print("Quitting...")
+                    break
+                elif key == ord("s"):
+                    print("Skipping to next image...")
+                    # Force skip by incrementing index
+                    current_idx = cap.get_current_index()
+                    cap.set_current_index(current_idx + 1)
+                elif key == ord("r"):
+                    print("Refreshing file list...")
+                    new_count = cap.force_refresh()
+                    print(f"Refreshed: now have {new_count} files")
+                elif key == ord("w"):
+                    # Toggle folder watching
+                    current_status = cap.is_folder_watching_enabled()
+                    cap.enable_folder_watching(not current_status)
+                    new_status = cap.is_folder_watching_enabled()
+                    print(f"Folder watching {'enabled' if new_status else 'disabled'}")
+
+            else:
+                print("No more frames available")
+                if not cap.loop:
+                    print("Reached end of image sequence (loop=False)")
+                    break
+
+        # cap.stop()
+        cap.disconnect()
+        cv2.destroyAllWindows()
+        print("FolderCapture test completed.")
+    else:
+        print(f"Failed to connect to folder: {folder}")
+        print(
+            "Make sure the folder exists and contains image files "
+            "(.jpg, .jpeg, .png, .bmp, .tiff, .tif)"
+        )
+
+
+if __name__ == "__main__":
+    _test_folder_capture()