endoreg-db 0.8.5.1__py3-none-any.whl

endoreg_db/models/media/video/video_file_frames/_extract_frames.py

@@ -0,0 +1,174 @@
+import logging
+from endoreg_db.models.media.video.video_file_io import _get_frame_dir_path
+from endoreg_db.utils.video.ffmpeg_wrapper import extract_frames as ffmpeg_extract_frames
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+from django.db import transaction
+
+
+import shutil
+logger = logging.getLogger(__name__)
+
+def _extract_frames(
+    video: "VideoFile",
+    quality: int = 2,
+    overwrite: bool = False,
+    ext="jpg",
+    verbose=False,
+) -> bool:
+    """
+    Extract frames from a raw video file, update frame extraction status in the database, and manage related file system operations.
+    
+    This function checks for existing extracted frames and skips extraction if appropriate, unless overwriting is requested. It handles deletion of existing frames when overwriting, invokes ffmpeg to extract frames, parses extracted frame numbers, updates corresponding database records, and manages video extraction state. Robust error handling ensures cleanup and state rollback on failure.
+    
+    Parameters:
+        video (VideoFile): The video object from which frames are to be extracted.
+        quality (int, optional): Quality parameter for ffmpeg extraction. Defaults to 2.
+        overwrite (bool, optional): Whether to overwrite existing extracted frames. Defaults to False.
+        ext (str, optional): File extension for extracted frames. Defaults to "jpg".
+    
+    Returns:
+        bool: True if extraction and updates succeed.
+    
+    Raises:
+        FileNotFoundError: If the raw video file is missing.
+        RuntimeError: If extraction or database update fails.
+        ValueError: If the frame directory path cannot be determined.
+    """
+    from ._delete_frames import _delete_frames
+    from endoreg_db.models.media.frame import Frame
+
+    # Pre-validation checks (outside any transaction)
+    if not video.has_raw:
+        raise FileNotFoundError(f"Raw video file not available for {video.uuid}. Cannot extract frames.")
+
+    raw_file_path = video.get_raw_file_path()
+    if not raw_file_path or not raw_file_path.exists():
+        raise FileNotFoundError(f"Raw video file not found at {raw_file_path} for video {video.uuid}. Cannot extract frames.")
+
+    frame_dir = _get_frame_dir_path(video)
+    if not frame_dir:
+        raise ValueError(f"Cannot determine frame directory path for video {video.uuid}.")
+
+    state = video.get_or_create_state()
+    frames_exist_in_db = Frame.objects.filter(video=video).exists()
+    files_exist_on_disk = frame_dir.exists() and any(frame_dir.iterdir())
+
+    # Fast-path: if frames exist and we are not overwriting, update state and return.
+    if (state.frames_extracted or files_exist_on_disk) and not overwrite:
+        logger.info(
+            "Frames already extracted or files exist for video %s, and overwrite=False. Skipping extraction.",
+            video.uuid,
+        )
+        if state.frames_extracted and frames_exist_in_db:
+            with transaction.atomic():
+                updated_count = Frame.objects.filter(video=video, is_extracted=False).update(is_extracted=True)
+                if updated_count > 0:
+                    logger.info(
+                        "Marked %d existing Frame objects as extracted for video %s based on state.",
+                        updated_count,
+                        video.uuid,
+                    )
+        elif not state.frames_extracted and files_exist_on_disk:
+            logger.warning(
+                "Files exist on disk for video %s but state.frames_extracted is False. Correcting state to match disk.",
+                video.uuid,
+            )
+            # Fix inconsistent state: files exist but state.frames_extracted is False
+            state.frames_extracted = True
+            state.save(update_fields=['frames_extracted'])
+            
+            # Also update Frame objects to be consistent
+            with transaction.atomic():
+                updated_count = Frame.objects.filter(video=video, is_extracted=False).update(is_extracted=True)
+                if updated_count > 0:
+                    logger.info(
+                        "Marked %d existing Frame objects as extracted for video %s after state correction.",
+                        updated_count,
+                        video.uuid,
+                    )
+        return True
+
+    # Overwrite: delete existing frames/files before re-extraction.
+    if overwrite:
+        logger.info("Overwrite=True. Preparing to delete existing frames/files for video %s before extraction.", video.uuid)
+        try:
+            _delete_frames(video)
+            with transaction.atomic():
+                updated_count = Frame.objects.filter(video=video, is_extracted=True).update(is_extracted=False)
+                if updated_count > 0:
+                    logger.info(
+                        "Reset %d Frame objects to is_extracted=False for video %s due to overwrite.",
+                        updated_count,
+                        video.uuid,
+                    )
+            state.refresh_from_db()
+        except Exception as del_e:
+            logger.error("Failed to delete existing frames for video %s during overwrite: %s", video.uuid, del_e, exc_info=True)
+            raise RuntimeError(f"Failed to delete existing frames for video {video.uuid} during overwrite.") from del_e
+
+    frame_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        logger.info("Starting frame extraction for video %s to %s", video.uuid, frame_dir)
+        # Step 1: Perform the long-running frame extraction outside any transaction.
+        extracted_paths = ffmpeg_extract_frames(raw_file_path, frame_dir, quality=quality, ext=ext)
+        if not extracted_paths:
+            logger.warning(
+                "ffmpeg_extract_frames returned no paths for video %s. Check video duration and ffmpeg logs.",
+                video.uuid,
+            )
+            if video.frame_count is not None and video.frame_count > 0:
+                raise RuntimeError(
+                    f"ffmpeg_extract_frames returned no paths for video {video.uuid}, but {video.frame_count} frames were expected."
+                )
+
+        logger.info("Successfully extracted %d frames using ffmpeg for video %s.", len(extracted_paths), video.uuid)
+
+        extracted_frame_numbers = []
+        for frame_path in extracted_paths:
+            try:
+                frame_number = int(frame_path.stem.split('_')[-1])
+                extracted_frame_numbers.append(frame_number)
+            except (ValueError, IndexError) as e:
+                logger.warning("Could not parse frame number from extracted file %s: %s", frame_path.name, e)
+
+        # Step 2: Perform all the quick DB updates inside a minimal atomic transaction.
+        with transaction.atomic():
+            if extracted_frame_numbers:
+                try:
+                    update_count = Frame.objects.filter(
+                        video=video, frame_number__in=extracted_frame_numbers
+                    ).update(is_extracted=True)
+                    logger.info("Marked %d Frame objects as is_extracted=True for video %s.", update_count, video.uuid)
+                    if update_count != len(extracted_frame_numbers):
+                        logger.warning(
+                            "Number of updated frames (%d) does not match number of parsed extracted files (%d) for video %s.",
+                            update_count,
+                            len(extracted_frame_numbers),
+                            video.uuid,
+                        )
+                except Exception as update_e:
+                    logger.error("Failed to update is_extracted flag for frames of video %s: %s", video.uuid, update_e, exc_info=True)
+            if extracted_paths:
+                state.refresh_from_db()
+                state.mark_frames_extracted()
+        return True
+
+    except Exception as e:
+        logger.error("Frame extraction or update failed for video %s: %s", video.uuid, e, exc_info=True)
+        logger.warning("Cleaning up frame directory %s for video %s due to extraction error.", frame_dir, video.uuid)
+        shutil.rmtree(frame_dir, ignore_errors=True)
+        try:
+            with transaction.atomic():
+                Frame.objects.filter(video=video, is_extracted=True).update(is_extracted=False)
+                state.refresh_from_db()
+                if state.frames_extracted:
+                    state.frames_extracted = False
+                    state.save(update_fields=["frames_extracted"])
+        except Exception as db_err:
+            logger.error("Failed to reset flags/state in DB during error handling for video %s: %s", video.uuid, db_err)
+        raise RuntimeError(f"Frame extraction or update failed for video {video.uuid}.") from e

endoreg_db/models/media/video/video_file_frames/_get_frame.py

@@ -0,0 +1,28 @@
+from typing import TYPE_CHECKING
+
+import logging
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile, Frame
+    
+logger = logging.getLogger(__name__)
+
+
+
+
+def _get_frame(video: "VideoFile", frame_number: int) -> "Frame":
+    """Gets a specific Frame object by its frame number."""
+    from endoreg_db.models import Frame
+    try:
+        # Access related manager directly
+        return video.frames.get(frame_number=frame_number)
+    except AttributeError:
+        logger.error("Could not access frame %d for video %s via related manager.", frame_number, video.uuid)
+        # Fallback query
+        return Frame.objects.get(video_file=video, frame_number=frame_number)
+    except Frame.DoesNotExist:
+        logger.error("Frame %d not found for video %s.", frame_number, video.uuid)
+        raise # Re-raise DoesNotExist
+    except Exception as e:
+        logger.error("Error getting frame %d for video %s: %s", frame_number, video.uuid, e, exc_info=True)
+        raise # Re-raise other exceptions

endoreg_db/models/media/video/video_file_frames/_get_frame_number.py

@@ -0,0 +1,27 @@
+
+from typing import TYPE_CHECKING
+
+import logging
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+    
+logger = logging.getLogger(__name__)
+
+
+
+
+def _get_frame_number(video: "VideoFile") -> int:
+    """Counts the number of associated Frame objects in the database."""
+    try:
+        # Access related manager directly
+        return video.frames.count()
+    except AttributeError:
+        logger.error("Could not access frame count for video %s. 'frames' related manager not found.", str(video))
+        # Fallback query (less efficient)
+        frame_model = video.get_frame_model()
+        return frame_model.objects.filter(video_file=video).count()
+    except Exception as e:
+        logger.error("Error counting frames for video %s: %s", video.uuid, e, exc_info=True)
+        return 0
+    

endoreg_db/models/media/video/video_file_frames/_get_frame_path.py

@@ -0,0 +1,20 @@
+# --- Frame Creation/Deletion ---
+import logging
+from typing import TYPE_CHECKING, Optional
+from pathlib import Path
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+logger = logging.getLogger(__name__)
+
+def _get_frame_path(video: "VideoFile", frame_number: int) -> Optional[Path]:
+    """Constructs the expected path for a given frame number."""
+    target_dir = video.get_frame_dir_path() # Use IO helper
+    if not target_dir:
+        logger.warning("Cannot get frame path for video %s: Frame directory not set.", video.uuid)
+        return None
+
+    frame_filename = f"frame_{frame_number:07d}.jpg"
+    path = target_dir / frame_filename
+    return path

endoreg_db/models/media/video/video_file_frames/_get_frame_paths.py

@@ -0,0 +1,27 @@
+from endoreg_db.models.media.video.video_file_io import _get_frame_dir_path
+
+from pathlib import Path
+import logging
+
+from typing import TYPE_CHECKING, List
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+logger = logging.getLogger(__name__)
+
+def _get_frame_paths(video: "VideoFile") -> List[Path]:
+    """Returns a sorted list of Path objects for extracted frame image files."""
+    frame_dir = _get_frame_dir_path(video)
+    if not frame_dir or not frame_dir.exists():
+        logger.warning("Frame directory %s does not exist for video %s.", frame_dir, video.uuid)
+        return []
+
+    frame_paths = list(frame_dir.glob('frame_*.jpg'))
+
+    try:
+        frame_paths.sort(key=lambda p: int(p.stem.split('_')[-1]))
+    except (ValueError, IndexError) as e:
+        logger.error("Error sorting frame paths in %s: %s. Found paths: %s", frame_dir, e, [p.name for p in frame_paths], exc_info=True)
+        logger.warning("Falling back to unsorted frame paths to preserve available data.")
+        return frame_paths
+    return frame_paths

endoreg_db/models/media/video/video_file_frames/_get_frame_range.py

@@ -0,0 +1,34 @@
+
+from typing import TYPE_CHECKING
+from django.db.models import QuerySet
+import logging
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile, Frame
+    
+logger = logging.getLogger(__name__)
+
+
+
+
+
+def _get_frame_range(video: "VideoFile", start_frame_number: int, end_frame_number: int) -> "QuerySet[Frame]":
+    """Gets a QuerySet of Frame objects within a specific range, ordered by frame number."""
+    from endoreg_db.models import Frame
+    try:
+        # Access related manager directly
+        return video.frames.filter(
+            frame_number__gte=start_frame_number,
+            frame_number__lte=end_frame_number,
+        ).order_by("frame_number")
+    except AttributeError:
+        logger.error("Could not access frame range for video %s via related manager.", video.uuid)
+        # Fallback query
+        return Frame.objects.filter(
+            video_file=video,
+            frame_number__gte=start_frame_number,
+            frame_number__lte=end_frame_number,
+        ).order_by("frame_number")
+    except Exception as e:
+        logger.error("Error getting frame range (%d-%d) for video %s: %s", start_frame_number, end_frame_number, video.uuid, e, exc_info=True)
+        return Frame.objects.none() # Return empty queryset on error

endoreg_db/models/media/video/video_file_frames/_get_frames.py

@@ -0,0 +1,27 @@
+from django.db.models import QuerySet
+
+from typing import TYPE_CHECKING
+
+import logging
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile, Frame
+    
+logger = logging.getLogger(__name__)
+
+
+
+
+def _get_frames(video: "VideoFile") -> "QuerySet[Frame]":
+    """Gets a QuerySet of all associated Frame objects, ordered by frame number."""
+    from endoreg_db.models import Frame
+    try:
+        # Access related manager directly
+        return video.frames.order_by("frame_number")
+    except AttributeError:
+        logger.error("Could not access frames for video %s. 'frames' related manager not found.", video.uuid)
+        # Fallback query
+        return Frame.objects.filter(video_file=video).order_by("frame_number")
+    except Exception as e:
+        logger.error("Error getting frames for video %s: %s", video.uuid, e, exc_info=True)
+        return Frame.objects.none() # Return empty queryset on error

endoreg_db/models/media/video/video_file_frames/_initialize_frames.py

@@ -0,0 +1,129 @@
+from tqdm import tqdm
+from pathlib import Path
+from typing import List
+from typing import TYPE_CHECKING, Optional
+import logging
+from django.db import OperationalError
+import time
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+    
+logger = logging.getLogger(__name__)
+
+
+def _initialize_frames(video: "VideoFile", frame_paths: Optional[List[Path]] = None):
+    """
+    Initializes Frame objects in the database based on either provided existing
+    frame paths or the expected frame count from the video metadata.
+
+    If `frame_paths` is provided, Frame objects are created/updated and marked
+    as `is_extracted=True`.
+    If `frame_paths` is None, Frame objects are created based on `video.frame_count`
+    and marked as `is_extracted=False`.
+
+    Updates state.frames_initialized and state.frame_count.
+    Uses bulk_create with ignore_conflicts=True, so it won't fail if frames already exist.
+
+    Raises RuntimeError on failure to create/update frames or update state.
+
+    State Transitions:
+        - On Success: Sets state.frames_initialized=True, state.frame_count=N.
+        - On Failure: Does not change state (error is raised).
+    """
+    from endoreg_db.models import Frame
+    from endoreg_db.models.media.video.video_file_frames._bulk_create_frames import _bulk_create_frames
+    from endoreg_db.models.media.video.video_file_frames._create_frame_object import _create_frame_object
+
+
+    frames_to_create = []
+    num_expected_or_provided = 0
+    mark_as_extracted = False
+
+    if frame_paths:
+        logger.info("Initializing Frame objects based on %d provided paths for video %s.", len(frame_paths), video.uuid)
+        mark_as_extracted = True
+        num_expected_or_provided = len(frame_paths)
+        for frame_path in tqdm(frame_paths, desc=f"Initializing Frames from Paths {video.uuid}", unit="frame"):
+            try:
+                frame_number = int(frame_path.stem.split('_')[-1])
+                relative_path_str = frame_path.name
+                frames_to_create.append(
+                    _create_frame_object(video, frame_number, relative_path_str, extracted=mark_as_extracted)
+                )
+            except (ValueError, IndexError) as e:
+                logger.warning("Could not parse frame number from %s: %s", frame_path.name, e)
+                continue
+    else:
+        expected_frame_count = video.frame_count
+        if expected_frame_count is None or expected_frame_count <= 0:
+            logger.warning("Cannot initialize frames for video %s: Frame count is %s.", video.uuid, expected_frame_count)
+            try:
+                state = video.get_or_create_state()
+                if state.frames_initialized or state.frame_count is not None:
+                    state.frames_initialized = False
+                    state.frame_count = None
+                    state.save(update_fields=['frames_initialized', 'frame_count'])
+            except Exception as state_e:
+                logger.error("Failed to reset state during empty initialization for video %s: %s", video.uuid, state_e, exc_info=True)
+            return
+
+        logger.info("Initializing %d expected Frame objects for video %s (is_extracted=False).", expected_frame_count, video.uuid)
+        mark_as_extracted = False
+        num_expected_or_provided = expected_frame_count
+        for frame_number in tqdm(range(expected_frame_count), desc=f"Initializing Expected Frames {video.uuid}", unit="frame"):
+            relative_path_str = f"frame_{frame_number:07d}.jpg"
+            frames_to_create.append(
+                _create_frame_object(video, frame_number, relative_path_str, extracted=mark_as_extracted)
+            )
+            
+    if frames_to_create:
+        for attempt in range(5):
+
+            try:
+                _bulk_create_frames(video, frames_to_create)
+                num_created_or_ignored = len(frames_to_create)
+                logger.info("Bulk create attempted for %d Frame objects for video %s (ignore_conflicts=True).", num_created_or_ignored, video.uuid)
+
+                if mark_as_extracted:
+                    frame_numbers_to_update = [f.frame_number for f in frames_to_create]
+                    if frame_numbers_to_update:
+                        update_count = Frame.objects.filter(
+                        video=video,
+                        frame_number__in=frame_numbers_to_update,
+                        is_extracted=False
+                        ).update(is_extracted=True)
+                        if update_count > 0:
+                            logger.info("Marked %d existing Frame objects as is_extracted=True for video %s.", update_count, video.uuid)
+
+                try:
+                    state = video.get_or_create_state()
+                    state.frames_initialized = True
+                    state.frame_count = num_expected_or_provided
+                    state.save(update_fields=['frames_initialized', 'frame_count'])
+                    logger.info("Set frames_initialized=True and frame_count=%d for video %s.", num_expected_or_provided, video.uuid)
+                except Exception as state_e:
+                    logger.error("Failed to update state after frame initialization for video %s: %s", video.uuid, state_e, exc_info=True)
+                    raise RuntimeError(f"Failed to update state after frame initialization for video {video.uuid}") from state_e
+
+            except OperationalError as e:
+                if "database is locked" in str(e):
+                    logger.warning("Database is locked, retrying frame initialization for video %s (attempt %d/5).", video.uuid, attempt + 1)
+                    time.sleep(2 ** attempt)
+                    if attempt < 4:
+                        continue
+                    else:
+                        raise RuntimeError(f"Failed to initialize frames for video {video.uuid}.") from e
+                logger.error("Error initializing frames for video %s: %s", video.uuid, e, exc_info=True)
+                raise RuntimeError(f"Failed to initialize frames for video {video.uuid}.") from e
+
+    else:
+        logger.warning("No valid frames found/generated to initialize for video %s.", video.uuid)
+        try:
+            state = video.get_or_create_state()
+            if state.frames_initialized or state.frame_count is not None:
+                state.frames_initialized = False
+                state.frame_count = None
+                state.save(update_fields=['frames_initialized', 'frame_count'])
+        except Exception as state_e:
+            logger.error("Failed to reset state during empty initialization for video %s: %s", video.uuid, state_e, exc_info=True)

endoreg_db/models/media/video/video_file_frames/_manage_frame_range.py

@@ -0,0 +1,141 @@
+import logging
+import os
+from typing import TYPE_CHECKING
+from django.db import transaction
+
+# Assuming ffmpeg_wrapper has or will have this function
+from endoreg_db.utils.video.ffmpeg_wrapper import extract_frame_range as ffmpeg_extract_frame_range
+
+from endoreg_db.models.media.video.video_file_io import _get_frame_dir_path
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+logger = logging.getLogger(__name__)
+
+def _delete_frame_range(video: "VideoFile", start_frame: int, end_frame: int):
+    """
+    Deletes frame image files within the specified range [start_frame, end_frame)
+    and updates their is_extracted status to False. Runs within the caller's transaction.
+    """
+
+    logger.info("Deleting frame files for video %s in range [%d, %d)", video.uuid, start_frame, end_frame)
+    frames_to_delete = video.frames.filter(
+        frame_number__gte=start_frame,
+        frame_number__lt=end_frame,
+        is_extracted=True
+    )
+
+    deleted_count = 0
+    paths_to_delete = [frame.file_path for frame in frames_to_delete]  # Get paths before potential DB changes
+
+    # Update DB first
+    update_count = frames_to_delete.update(is_extracted=False)
+    logger.info("Marked %d Frame objects as is_extracted=False for video %s range [%d, %d).",
+                update_count, video.uuid, start_frame, end_frame)
+
+    # Then delete files
+    for frame_path in paths_to_delete:
+        try:
+            if frame_path.exists():
+                os.remove(frame_path)
+                deleted_count += 1
+        except Exception as e:
+            # Log warning but continue; DB state is already updated.
+            logger.warning("Could not delete frame file %s for video %s: %s", frame_path, video.uuid, e)
+
+    logger.info("Attempted deletion of %d files for video %s range [%d, %d). Actual deleted: %d.",
+                len(paths_to_delete), video.uuid, start_frame, end_frame, deleted_count)
+
+
+
+
+@transaction.atomic
+def _extract_frame_range(
+    video: "VideoFile",
+    start_frame: int,
+    end_frame: int,
+    quality: int = 2,
+    overwrite: bool = False,
+    ext="jpg",
+    verbose=False,
+) -> bool:
+    """
+    Extracts frames within the range [start_frame, end_frame) using ffmpeg.
+    Updates corresponding Frame objects' is_extracted flag.
+    Runs within the caller's transaction.
+    Does NOT update VideoState.frames_extracted.
+    """
+
+    if not video.has_raw:
+        raise FileNotFoundError(f"Raw video file not available for {video.uuid}. Cannot extract frame range.")
+
+    raw_file_path = video.get_raw_file_path()
+    if not raw_file_path or not raw_file_path.exists():
+        raise FileNotFoundError(f"Raw video file not found at {raw_file_path} for video {video.uuid}. Cannot extract frame range.")
+
+    frame_dir = _get_frame_dir_path(video)
+    if not frame_dir:
+        raise ValueError(f"Cannot determine frame directory path for video {video.uuid}.")
+
+    # Check frames within the range that might already exist
+    frames_in_range = video.frames.filter(
+        frame_number__gte=start_frame,
+        frame_number__lt=end_frame
+    )
+    existing_extracted_in_range = frames_in_range.filter(is_extracted=True)
+
+    if existing_extracted_in_range.exists():
+        if overwrite:
+            logger.info("Overwrite=True, deleting existing frame files in range [%d, %d) for video %s before extraction.", start_frame, end_frame, video.uuid)
+            _delete_frame_range(video, start_frame, end_frame)
+        else:
+            logger.info("Frames already exist in range [%d, %d) for video %s and overwrite=False. Skipping extraction for this range.", start_frame, end_frame, video.uuid)
+            updated_count = frames_in_range.filter(is_extracted=False).update(is_extracted=True)
+            if updated_count > 0:
+                logger.info("Marked %d existing Frame objects in range [%d, %d) as extracted for video %s.", updated_count, start_frame, end_frame, video.uuid)
+            return True  # Indicate success as frames are considered present
+
+    frame_dir.mkdir(parents=True, exist_ok=True)
+    extracted_paths = []
+
+    try:
+        logger.info("Starting frame range extraction [%d, %d) for video %s to %s", start_frame, end_frame, video.uuid, frame_dir)
+        extracted_paths = ffmpeg_extract_frame_range(
+            raw_file_path, frame_dir, start_frame, end_frame, quality=quality, ext=ext
+        )
+
+        logger.info("ffmpeg extraction process completed for video %s range [%d, %d). Found %d files.", video.uuid, start_frame, end_frame, len(extracted_paths))
+
+        update_count = frames_in_range.update(is_extracted=True)
+        logger.info("Marked %d Frame objects in range [%d, %d) as is_extracted=True for video %s.", update_count, start_frame, end_frame, video.uuid)
+
+        return True
+
+    except FileNotFoundError as err:
+        logger.error(
+            "Frame range extraction [%d, %d) failed for video %s: %s",
+            start_frame,
+            end_frame,
+            video.uuid,
+            err,
+            exc_info=True,
+        )
+        raise
+
+    except Exception as e:
+        logger.error("Frame range extraction [%d, %d) or DB update failed for video %s: %s", start_frame, end_frame, video.uuid, e, exc_info=True)
+
+        logger.warning("Attempting file cleanup in range [%d, %d) for video %s due to extraction error.", start_frame, end_frame, video.uuid)
+        files_to_check = extracted_paths if 'extracted_paths' in locals() and extracted_paths else []
+        if not files_to_check:
+            files_to_check = [frame_dir / f"frame_{i:07d}.{ext}" for i in range(start_frame, end_frame)]
+
+        for potential_file in files_to_check:
+            if potential_file.exists():
+                try:
+                    os.remove(potential_file)
+                except OSError as unlink_err:
+                    logger.error("Failed to delete potential frame %s during cleanup: %s", potential_file, unlink_err)
+
+        raise RuntimeError(f"Frame range extraction or update failed for video {video.uuid} range [{start_frame}, {end_frame}).") from e