endoreg-db 0.8.1__py3-none-any.whl → 0.8.2.1__py3-none-any.whl

endoreg_db/urls/__init__.py

@@ -25,7 +25,6 @@ from .label_video_segments import url_patterns as label_video_segments_url_patte
 from .label_video_segment_validate import url_patterns as label_video_segment_validate_url_patterns
 # TODO Phase 1.2: Implement VideoMediaView and PDFMediaView before enabling
 # from .media import urlpatterns as media_url_patterns
-from .sensitive_meta import urlpatterns as pdf_url_patterns
 from .report import url_patterns as report_url_patterns
 from .upload import urlpatterns as upload_url_patterns
 from .video import url_patterns as video_url_patterns
@@ -43,7 +42,6 @@ api_urls += label_video_segments_url_patterns
 api_urls += label_video_segment_validate_url_patterns  # Neue Validierungs-Endpunkte
 # Phase 1.2: Enable media_url_patterns ✅ IMPLEMENTED
 api_urls += media_url_patterns
-api_urls += pdf_url_patterns
 api_urls += report_url_patterns
 api_urls += upload_url_patterns
 api_urls += video_url_patterns

endoreg_db/urls/media.py

@@ -2,11 +2,35 @@ from django.urls import path
 
 from endoreg_db.views.media import (
     VideoMediaView,
-    PDFMediaManagementView as PDFMediaView,  # Alias to avoid conflict with legacy pdf.PDFMediaView
+    PdfMediaView,  # Alias to avoid conflict with legacy pdf.PDFMediaView
+    video_segments_by_pk,
+    video_segments_collection,
+    video_segments_by_video,
+    video_segment_detail,
+    video_segments_stats,
+    video_segment_validate,
+    video_segments_validate_bulk,
+    video_segments_validation_status,
+    video_sensitive_metadata,
+    video_sensitive_metadata_verify,
+    pdf_sensitive_metadata,
+    pdf_sensitive_metadata_verify,
+    sensitive_metadata_list,
+    pdf_sensitive_metadata_list,
 )
 from endoreg_db.views import (
     VideoStreamView,
 )
+from endoreg_db.views.pdf.reimport import PdfReimportView
+from endoreg_db.views.video.reimport import VideoReimportView
+from endoreg_db.views.video.correction import (
+    VideoReprocessView,
+    VideoMetadataView,
+    VideoProcessingHistoryView,
+    VideoAnalyzeView,
+    VideoApplyMaskView,
+    VideoRemoveFramesView,
+)
 # ---------------------------------------------------------------------------------------
 # ANNOTATION API ENDPOINTS
 #
@@ -23,10 +47,183 @@ urlpatterns = [
     path("media/videos/<int:pk>/", VideoStreamView.as_view(), name="video-detail-stream"),  # Support ?type= params
     path("media/videos/<int:pk>/details/", VideoMediaView.as_view(), name="video-detail"),  # JSON metadata
     path("media/videos/<int:pk>/stream/", VideoStreamView.as_view(), name="video-stream"),  # Legacy support
+    
+    # Video Re-import API endpoint (modern media framework)
+    # POST /api/media/videos/<int:pk>/reimport/
+    # Re-imports a video file to regenerate metadata when OCR failed or data is incomplete
+    path("media/videos/<int:pk>/reimport/", VideoReimportView.as_view(), name="video-reimport"),
+    
+    # ---------------------------------------------------------------------------------------
+    # VIDEO CORRECTION API ENDPOINTS (Modern Media Framework - October 14, 2025)
+    #
+    # All video correction endpoints migrated to unified /api/media/videos/<pk>/ pattern
+    # These endpoints enable video correction workflows (Phase 1.1):
+    # - Analysis: Detect sensitive frames using MiniCPM-o 2.6 or OCR+LLM
+    # - Masking: Apply device-specific masks or custom ROI masks
+    # - Frame Removal: Remove sensitive frames from videos
+    # - Reprocessing: Re-run entire anonymization pipeline
+    # - Metadata: View analysis results
+    # - History: Track all correction operations
+    # ---------------------------------------------------------------------------------------
+    
+    # Video Metadata API
+    # GET /api/media/videos/<int:pk>/metadata/
+    # Returns analysis results (sensitive frame count, ratio, frame IDs)
+    path("media/videos/<int:pk>/metadata/", VideoMetadataView.as_view(), name="video-metadata"),
+    
+    # Video Processing History API
+    # GET /api/media/videos/<int:pk>/processing-history/
+    # Returns history of all processing operations (masking, frame removal, analysis)
+    path("media/videos/<int:pk>/processing-history/", VideoProcessingHistoryView.as_view(), name="video-processing-history"),
+    
+    # Video Analysis API
+    # POST /api/media/videos/<int:pk>/analyze/
+    # Analyzes video for sensitive frames using MiniCPM-o 2.6 or OCR+LLM
+    # Body: { detection_method: 'minicpm'|'ocr_llm'|'hybrid', sample_interval: 30 }
+    path("media/videos/<int:pk>/analyze/", VideoAnalyzeView.as_view(), name="video-analyze"),
+    
+    # Video Masking API
+    # POST /api/media/videos/<int:pk>/apply-mask/
+    # Applies device mask or custom ROI mask to video
+    # Body: { mask_type: 'device'|'custom', device_name: 'olympus', roi: {...} }
+    path("media/videos/<int:pk>/apply-mask/", VideoApplyMaskView.as_view(), name="video-apply-mask"),
+    
+    # Video Frame Removal API
+    # POST /api/media/videos/<int:pk>/remove-frames/
+    # Removes specified frames from video
+    # Body: { frame_list: [10,20,30] OR frame_ranges: '10-20,30' OR detection_method: 'automatic' }
+    path("media/videos/<int:pk>/remove-frames/", VideoRemoveFramesView.as_view(), name="video-remove-frames"),
+    
+    # Video Reprocess API endpoint (modern media framework)
+    # POST /api/media/videos/<int:pk>/reprocess/
+    # Re-runs entire anonymization pipeline for a video (correction workflow)
+    path("media/videos/<int:pk>/reprocess/", VideoReprocessView.as_view(), name="video-reprocess"),
+    
+    # ---------------------------------------------------------------------------------------
+    # VIDEO SEGMENT API ENDPOINTS (Modern Media Framework - October 14, 2025)
+    #
+    # Unified segment management endpoints replacing legacy /api/video-segments/
+    # Collection: GET/POST all segments across videos
+    # Video-scoped: GET/POST segments for specific video
+    # Detail: GET/PATCH/DELETE individual segment
+    # ---------------------------------------------------------------------------------------
+    
+    # Video Segments Collection API
+    # GET/POST /api/media/videos/segments/
+    # List all video segments across videos or create new segment
+    path("media/videos/segments/", video_segments_collection, name="video-segments-collection"),
+    
+    # Video Segments Stats API
+    # GET /api/media/videos/segments/stats/
+    # Get statistics about video segments
+    path("media/videos/segments/stats/", video_segments_stats, name="video-segments-stats"),
+    
+    # Video-Specific Segments API
+    # GET/POST /api/media/videos/<int:pk>/segments/
+    # List segments for specific video or create segment for video
+    path("media/videos/<int:pk>/segments/", video_segments_by_video, name="video-segments-by-video"),
+    
+    # Segment Detail API
+    # GET /api/media/videos/<int:pk>/segments/<int:segment_id>/
+    # PATCH /api/media/videos/<int:pk>/segments/<int:segment_id>/
+    # DELETE /api/media/videos/<int:pk>/segments/<int:segment_id>/
+    # Manages individual segment operations
+    path("media/videos/<int:pk>/segments/<int:segment_id>/", video_segment_detail, name="video-segment-detail"),
+    
+    # ---------------------------------------------------------------------------------------
+    # VIDEO SEGMENT VALIDATION API ENDPOINTS (Modern Media Framework - October 14, 2025)
+    #
+    # Unified validation endpoints replacing legacy /api/label-video-segment/*/validate/
+    # Single: POST validate individual segment
+    # Bulk: POST validate multiple segments
+    # Status: GET/POST validation status for all segments
+    # ---------------------------------------------------------------------------------------
+    
+    # Single Segment Validation API
+    # POST /api/media/videos/<int:pk>/segments/<int:segment_id>/validate/
+    # Validates a single video segment
+    # Body: { "is_validated": true, "notes": "..." }
+    path("media/videos/<int:pk>/segments/<int:segment_id>/validate/", video_segment_validate, name="video-segment-validate"),
+    
+    # Bulk Segment Validation API
+    # POST /api/media/videos/<int:pk>/segments/validate-bulk/
+    # Validates multiple segments at once
+    # Body: { "segment_ids": [1,2,3], "is_validated": true, "notes": "..." }
+    path("media/videos/<int:pk>/segments/validate-bulk/", video_segments_validate_bulk, name="video-segments-validate-bulk"),
+    
+    # Segment Validation Status API
+    # GET /api/media/videos/<int:pk>/segments/validation-status/
+    # Returns validation statistics for all segments
+    # POST /api/media/videos/<int:pk>/segments/validation-status/
+    # Marks all segments (or filtered by label) as validated
+    # Body: { "label_name": "polyp", "notes": "..." }
+    path("media/videos/<int:pk>/segments/validation-status/", video_segments_validation_status, name="video-segments-validation-status"),
+
+    # ---------------------------------------------------------------------------------------
+    # SENSITIVE METADATA ENDPOINTS (Modern Media Framework)
+    # ---------------------------------------------------------------------------------------
+    
+    # Video Sensitive Metadata (Resource-Scoped)
+    # GET/PATCH /api/media/videos/<pk>/sensitive-metadata/
+    # Get or update sensitive patient data for a video
+    path(
+        "media/videos/<int:pk>/sensitive-metadata/",
+        video_sensitive_metadata,
+        name="video-sensitive-metadata"
+    ),
+    
+    # POST /api/media/videos/<pk>/sensitive-metadata/verify/
+    # Update verification state (dob_verified, names_verified)
+    path(
+        "media/videos/<int:pk>/sensitive-metadata/verify/",
+        video_sensitive_metadata_verify,
+        name="video-sensitive-metadata-verify"
+    ),
+    
+    # PDF Sensitive Metadata (Resource-Scoped)
+    # GET/PATCH /api/media/pdfs/<pk>/sensitive-metadata/
+    # Get or update sensitive patient data for a PDF
+    path(
+        "media/pdfs/<int:pk>/sensitive-metadata/",
+        pdf_sensitive_metadata,
+        name="pdf-sensitive-metadata"
+    ),
+    
+    # POST /api/media/pdfs/<pk>/sensitive-metadata/verify/
+    # Update verification state (dob_verified, names_verified)
+    path(
+        "media/pdfs/<int:pk>/sensitive-metadata/verify/",
+        pdf_sensitive_metadata_verify,
+        name="pdf-sensitive-metadata-verify"
+    ),
+    
+    # List Endpoints (Collection-Level)
+    # GET /api/media/sensitive-metadata/
+    # List all sensitive metadata (combined PDFs and Videos)
+    # Supports filtering: ?content_type=pdf|video&verified=true&search=name
+    path(
+        "media/sensitive-metadata/",
+        sensitive_metadata_list,
+        name="sensitive-metadata-list"
+    ),
+    
+    # GET /api/media/pdfs/sensitive-metadata/
+    # List sensitive metadata for PDFs only
+    # Replaces legacy /api/pdf/sensitivemeta/list/
+    path(
+        "media/pdfs/sensitive-metadata/",
+        pdf_sensitive_metadata_list,
+        name="pdf-sensitive-metadata-list"
+    ),
 
     # PDF media endpoints
-    path("media/pdfs/", PDFMediaView.as_view(), name="pdf-list"),
-    path("media/pdfs/<int:pk>/", PDFMediaView.as_view(), name="pdf-detail"),
-    path("media/pdfs/<int:pk>/stream/", PDFMediaView.as_view(), name="pdf-stream"),
+    path("media/pdfs/", PdfMediaView.as_view(), name="pdf-list"),
+    path("media/pdfs/<int:pk>/", PdfMediaView.as_view(), name="pdf-detail"),
+    path("media/pdfs/<int:pk>/stream/", PdfMediaView.as_view(), name="pdf-stream"),
+
+    # PDF Re-import API endpoint (modern media framework)
+    # POST /api/media/pdfs/<int:pk>/reimport/
+    # Re-imports a PDF file to regenerate metadata when OCR failed or data is incomplete
+    path("media/pdfs/<int:pk>/reimport/", PdfReimportView.as_view(), name="pdf-reimport"),
 ]
     # ---------------------------------------------------------------------------------------

endoreg_db/urls/report.py

@@ -2,10 +2,7 @@ from django.urls import path
 from endoreg_db.views import (
     ReportListView,
     ReportWithSecureUrlView,
-    SecureFileUrlView,
     ReportFileMetadataView,
-    SecureFileServingView,
-    validate_secure_url,
 )
 
 url_patterns = [        # ---------------------------------------------------------------------------------------
@@ -40,16 +37,6 @@ url_patterns = [        # ------------------------------------------------------
             name='report_with_secure_url'
         ),
 
-        # API-Endpunkt für manuelle sichere URL-Generierung  
-        # POST /api/secure-file-urls/
-        # Body: {"report_id": 123, "file_type": "pdf"}
-        # Generiert eine neue sichere URL für einen bestehenden Report
-        path(
-            'secure-file-urls/', 
-            SecureFileUrlView.as_view(), 
-            name='generate_secure_file_url'
-        ),
-
         # API-Endpunkt für Report-Datei-Metadaten
         # GET /api/reports/{report_id}/file-metadata/
         # Gibt Datei-Metadaten zurück (Größe, Typ, Datum, etc.)
@@ -58,21 +45,4 @@ url_patterns = [        # ------------------------------------------------------
             ReportFileMetadataView.as_view(), 
             name='report_file_metadata'
         ),
-
-        # Sichere Datei-Serving-Endpunkt mit Token-Validierung
-        # GET /api/reports/{report_id}/secure-file/?token={token}
-        # Serviert die tatsächliche Datei über eine sichere, tokenbasierte URL
-        path(
-            'reports/<int:report_id>/secure-file/', 
-            SecureFileServingView.as_view(), 
-            name='secure_file_serving'
-        ),
-        # URL-Validierungs-Endpunkt
-        # GET /api/validate-secure-url/?url={url}
-        # Validiert, ob eine sichere URL noch gültig ist
-        path(
-            'validate-secure-url/', 
-            validate_secure_url, 
-            name='validate_secure_url'
-        ),
 ]

endoreg_db/urls/sensitive_meta.py

@@ -1,36 +0,0 @@
-from django.urls import path
-
-# Prefer explicit imports to avoid relying on parent __init__ exports
-from endoreg_db.views import (
-    SensitiveMetaDetailView,
-    SensitiveMetaVerificationView,
-    SensitiveMetaListView,
-)
-
-urlpatterns = [
-
-    # Sensitive Meta Detail API
-    path(
-        'pdf/sensitivemeta/<int:sensitive_meta_id>/', 
-        SensitiveMetaDetailView.as_view(), 
-        name='sensitive_meta_detail'
-    ),
-    # Alternative endpoint for query parameter access (backward compatibility)
-    path(
-        'pdf/sensitivemeta/', 
-        SensitiveMetaDetailView.as_view(), 
-        name='sensitive_meta_query'
-    ),
-
-    # Sensitive Meta Verification API
-    path(
-        'pdf/sensitivemeta/verify/', 
-        SensitiveMetaVerificationView.as_view(), 
-        name='sensitive_meta_verify'),
-
-    # Sensitive Meta List API
-    path(
-        'pdf/sensitivemeta/list/', 
-        SensitiveMetaListView.as_view(), 
-        name='sensitive_meta_list'),
-]

endoreg_db/urls/video.py

@@ -1,17 +1,10 @@
 from django.urls import path
 
 from endoreg_db.views import (
-    VideoReimportView,
     SensitiveMetaDetailView,
     VideoLabelView,
-    VideoStreamView,
-    # Video Correction Views (Phase 1.1)
-    VideoMetadataView,
-    VideoProcessingHistoryView,
-    VideoAnalyzeView,
-    VideoApplyMaskView,
-    VideoRemoveFramesView,
-    VideoReprocessView,
+    # Note: VideoStreamView moved to modern media framework. See: endoreg_db/urls/media.py
+    # Note: All Video Correction Views moved to modern media framework. See: endoreg_db/urls/media.py
 )
 
 url_patterns = [
@@ -24,23 +17,22 @@ url_patterns = [
         name='video_label_segments'
     ),
     
-    # Video streaming API endpoint
-    # GET /api/videostream/<int:pk>/
-    # Streams the raw video file with HTTP range and CORS support
-    path(
-        'videostream/<int:pk>/', 
-        VideoStreamView.as_view(), 
-        name='video_stream'
-    ),
+    # ---------------------------------------------------------------------------------------
+    # VIDEO STREAMING - MOVED TO MODERN MEDIA FRAMEWORK
+    #
+    # Video streaming endpoint has been migrated to the media framework
+    # as of October 14, 2025. Please use the new endpoints:
+    #
+    # OLD → NEW:
+    # GET /api/videostream/<pk>/              → GET /api/media/videos/<pk>/
+    # GET /api/videostream/<pk>/              → GET /api/media/videos/<pk>/stream/
+    #
+    # See: endoreg_db/urls/media.py for new URL registrations
+    # ---------------------------------------------------------------------------------------
+    
+    # Note: Video Re-import moved to modern media framework
+    # See: endoreg_db/urls/media.py - POST /api/media/videos/<int:pk>/reimport/
     
-    # Video Re-import API endpoint
-    # POST /api/video/<int:video_id>/reimport/
-    # Re-imports a video file to regenerate metadata when OCR failed or data is incomplete
-    path(
-        'video/<int:video_id>/reimport/', 
-        VideoReimportView.as_view(), 
-        name='video_reimport'
-    ),
     # Video Sensitive Meta endpoints (for video anonymization)
     # GET /api/video/sensitivemeta/<int:sensitive_meta_id>/
     # PATCH /api/video/sensitivemeta/<int:sensitive_meta_id>/
@@ -51,69 +43,19 @@ url_patterns = [
     ),
     
     # ---------------------------------------------------------------------------------------
-    # VIDEO CORRECTION API ENDPOINTS (Phase 1.1)
+    # VIDEO CORRECTION API ENDPOINTS - MOVED TO MODERN MEDIA FRAMEWORK
+    #
+    # All video correction endpoints have been migrated to the modern media framework
+    # as of October 14, 2025. Please use the new endpoints:
+    #
+    # OLD → NEW:
+    # GET  /api/video-metadata/<id>/              → GET  /api/media/videos/<pk>/metadata/
+    # GET  /api/video-processing-history/<id>/    → GET  /api/media/videos/<pk>/processing-history/
+    # POST /api/video-analyze/<id>/               → POST /api/media/videos/<pk>/analyze/
+    # POST /api/video-apply-mask/<id>/            → POST /api/media/videos/<pk>/apply-mask/
+    # POST /api/video-remove-frames/<id>/         → POST /api/media/videos/<pk>/remove-frames/
+    # POST /api/video-reprocess/<id>/             → POST /api/media/videos/<pk>/reprocess/
     #
-    # These endpoints enable video correction workflows:
-    # - Analysis: Detect sensitive frames using MiniCPM-o 2.6 or OCR+LLM
-    # - Masking: Apply device-specific masks or custom ROI masks
-    # - Frame Removal: Remove sensitive frames from videos
-    # - Processing History: Track all correction operations
+    # See: endoreg_db/urls/media.py for new URL registrations
     # ---------------------------------------------------------------------------------------
-    
-    # Video Metadata API
-    # GET /api/video-metadata/<int:id>/
-    # Returns analysis results (sensitive frame count, ratio, frame IDs)
-    path(
-        'video-metadata/<int:id>/',
-        VideoMetadataView.as_view(),
-        name='video_metadata'
-    ),
-    
-    # Video Processing History API
-    # GET /api/video-processing-history/<int:id>/
-    # Returns history of all processing operations (masking, frame removal, analysis)
-    path(
-        'video-processing-history/<int:id>/',
-        VideoProcessingHistoryView.as_view(),
-        name='video_processing_history'
-    ),
-    
-    # Video Analysis API
-    # POST /api/video-analyze/<int:id>/
-    # Analyzes video for sensitive frames using MiniCPM-o 2.6 or OCR+LLM
-    # Body: { detection_method: 'minicpm'|'ocr_llm'|'hybrid', sample_interval: 30 }
-    path(
-        'video-analyze/<int:id>/',
-        VideoAnalyzeView.as_view(),
-        name='video_analyze'
-    ),
-    
-    # Video Masking API
-    # POST /api/video-apply-mask/<int:id>/
-    # Applies device mask or custom ROI mask to video
-    # Body: { mask_type: 'device'|'custom', device_name: 'olympus', roi: {...} }
-    path(
-        'video-apply-mask/<int:id>/',
-        VideoApplyMaskView.as_view(),
-        name='video_apply_mask'
-    ),
-    
-    # Frame Removal API
-    # POST /api/video-remove-frames/<int:id>/
-    # Removes specified frames from video
-    # Body: { frame_list: [10,20,30] OR frame_ranges: '10-20,30' OR detection_method: 'automatic' }
-    path(
-        'video-remove-frames/<int:id>/',
-        VideoRemoveFramesView.as_view(),
-        name='video_remove_frames'
-    ),
-    
-    # Video Reprocessing API
-    # POST /api/video-reprocess/<int:id>/
-    # Re-runs entire anonymization pipeline for a video
-    path(
-        'video-reprocess/<int:id>/',
-        VideoReprocessView.as_view(),
-        name='video_reprocess'
-    ),
 ]

endoreg_db/utils/paths.py

@@ -8,19 +8,12 @@ It provides a unified dictionary 'data_paths' for accessing all path objects.
 from logging import getLogger
 logger = getLogger(__name__)
 
-import os
 from pathlib import Path
 from typing import Dict
-import dotenv
 
-# Only load .env in non-pytest contexts to avoid leaking dev settings into tests
-if not os.environ.get("PYTEST_CURRENT_TEST"):
-    dotenv.load_dotenv()
-else:
-    logger.debug("Skipping .env load under pytest")
+from endoreg_db.config.env import env_path
 
-# Define BASE_DIR as the project root (endoreg_db/utils -> endoreg_db -> repo root)
-STORAGE_DIR = Path(os.getenv("STORAGE_DIR"))
+STORAGE_DIR = env_path("STORAGE_DIR", "storage")
 
 # Resolve STORAGE_DIR from env or default under BASE_DIR
 #def _resolve_storage_dir() -> Path:
@@ -36,7 +29,6 @@ STORAGE_DIR = Path(os.getenv("STORAGE_DIR"))
 STORAGE_DIR.mkdir(parents=True, exist_ok=True)
 
 PREFIX_RAW = "raw_"
-STORAGE_DIR_NAME = "data"
 IMPORT_DIR_NAME = "import"
 EXPORT_DIR_NAME = "export"
 

endoreg_db/utils/video/ffmpeg_wrapper.py

@@ -1,6 +1,8 @@
+import os
 import subprocess
 import json
 import logging
+from functools import lru_cache
 from pathlib import Path
 from typing import List, Dict, Optional, Tuple
 import cv2
@@ -13,6 +15,67 @@ logger = logging.getLogger("ffmpeg_wrapper")
 _nvenc_available = None
 _preferred_encoder = None
 
+
+@lru_cache(maxsize=1)
+def _resolve_ffmpeg_executable() -> Optional[str]:
+    """Locate the ffmpeg executable using multiple discovery strategies."""
+    # 1) Explicit overrides via env vars
+    env_candidates = [
+        os.environ.get("FFMPEG_EXECUTABLE"),
+        os.environ.get("FFMPEG_BINARY"),
+        os.environ.get("FFMPEG_PATH"),
+    ]
+
+    # 2) Django settings overrides (if Django is configured)
+    try:
+        from django.conf import settings  # type: ignore
+
+        env_candidates.extend(
+            getattr(settings, attr)
+            for attr in ("FFMPEG_EXECUTABLE", "FFMPEG_BINARY", "FFMPEG_PATH")
+            if hasattr(settings, attr)
+        )
+    except Exception:
+        # Django might not be configured for every consumer
+        pass
+
+    # Normalize and verify explicit candidates
+    for candidate in env_candidates:
+        if not candidate:
+            continue
+        candidate_path = Path(candidate)
+        if candidate_path.is_dir():
+            candidate_path = candidate_path / "ffmpeg"
+        if candidate_path.exists() and os.access(candidate_path, os.X_OK):
+            logger.debug("Using ffmpeg executable override at %s", candidate_path)
+            return str(candidate_path)
+
+    # 3) PATH lookup (shutil.which)
+    via_path = shutil.which("ffmpeg")
+    if via_path:
+        return via_path
+
+    # 4) Common fallback locations (useful for Nix-based environments)
+    nix_store = Path("/nix/store")
+    if nix_store.exists():
+        patterns = (
+            "*-ffmpeg-*/bin/ffmpeg",
+            "*-ffmpeg-headless-*/bin/ffmpeg",
+            "*-ffmpeg-headless*/bin/ffmpeg",
+        )
+        for pattern in patterns:
+            matches = sorted(nix_store.glob(pattern))
+            if matches:
+                logger.debug("Discovered ffmpeg in nix store at %s", matches[-1])
+                return str(matches[-1])
+
+    # 5) Final fallback to standard Unix locations
+    for fallback in (Path("/usr/bin/ffmpeg"), Path("/usr/local/bin/ffmpeg")):
+        if fallback.exists() and os.access(fallback, os.X_OK):
+            return str(fallback)
+
+    return None
+
 def _detect_nvenc_support() -> bool:
     """
     Detect if NVIDIA NVENC hardware acceleration is available.
@@ -163,7 +226,7 @@ def is_ffmpeg_available() -> bool:
     Returns:
         True if FFmpeg is found in the PATH; otherwise, False.
     """
-    return shutil.which("ffmpeg") is not None
+    return _resolve_ffmpeg_executable() is not None
 
 def check_ffmpeg_availability():
     """
@@ -607,8 +670,8 @@ def extract_frames(
     Returns:
         A list of Path objects for the extracted frames.
     """
-    # Check if ffmpeg command exists
-    ffmpeg_executable = shutil.which("ffmpeg")
+    # Resolve ffmpeg executable with multiple fallbacks
+    ffmpeg_executable = _resolve_ffmpeg_executable()
     if not ffmpeg_executable:
         error_msg = "ffmpeg command not found. Ensure FFmpeg is installed and in the system's PATH."
         logger.error(error_msg)
@@ -691,7 +754,7 @@ def extract_frame_range(
         logger.warning("extract_frame_range called with start_frame (%d) >= end_frame (%d). No frames to extract.", start_frame, end_frame)
         return []
 
-    ffmpeg_executable = shutil.which("ffmpeg")
+    ffmpeg_executable = _resolve_ffmpeg_executable()
     if not ffmpeg_executable:
         error_msg = "ffmpeg command not found. Ensure FFmpeg is installed and in the system's PATH."
         logger.error(error_msg)