media-engine 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

media_engine/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.1'
-__version_tuple__ = version_tuple = (0, 1, 1)
+__version__ = version = '0.2.1'
+__version_tuple__ = version_tuple = (0, 2, 1)
 
 __commit_id__ = commit_id = None

media_engine/batch/models.py

@@ -57,6 +57,15 @@ class BatchRequest(BaseModel):
     # Optional LUT path for visual analysis (e.g., for log footage color correction)
     # Applied to extracted frames before sending to Qwen
     lut_path: str | None = None
+    # Per-file batch overlap setting for visual analysis (file path -> bool)
+    # When True, batches overlap by 1 frame for visual continuity (useful for unstable camera)
+    # Example: {"/path/shaky_video.mp4": True}
+    visual_batch_overlap: dict[str, bool] | None = None
+    # Per-file Qwen strategy override (file path -> strategy)
+    # Overrides global qwen_strategy setting for specific files
+    # Values: "single", "context", "batch", "batch_context"
+    # Example: {"/path/action_video.mp4": "batch_context"}
+    visual_strategy: dict[str, str] | None = None
 
 
 class BatchFileStatus(BaseModel):

media_engine/batch/processor.py

@@ -85,7 +85,7 @@ def run_batch_job(batch_id: str, request: BatchRequest) -> None:
     yolo_model = settings.get_yolo_model()
     clip_model = settings.get_clip_model()
 
-    logger.info(f"Batch {batch_id} models: whisper={whisper_model}, qwen={qwen_model}, " f"yolo={yolo_model}, clip={clip_model}")
+    logger.info(f"Batch {batch_id} models: whisper={whisper_model}, qwen={qwen_model}, yolo={yolo_model}, clip={clip_model}")
 
     batch_start_time = time.time()
     peak_memory = get_memory_mb()
@@ -117,7 +117,7 @@ def run_batch_job(batch_id: str, request: BatchRequest) -> None:
 
         # Add time for remaining extractors (after current one)
         remaining_extractors = EXTRACTOR_ORDER[current_ext_idx + 1 :]
-        logger.info(f"ETA calc: current={current_extractor}, remaining={remaining_extractors}, " f"enabled={enabled_extractors}")
+        logger.info(f"ETA calc: current={current_extractor}, remaining={remaining_extractors}, enabled={enabled_extractors}")
 
         for ext in remaining_extractors:
             if ext not in enabled_extractors:
@@ -210,7 +210,7 @@ def run_batch_job(batch_id: str, request: BatchRequest) -> None:
 
         # Debug logging for ETA calculation (use INFO level to see it)
         if total_eta and total_eta > 0:
-            logger.info(f"ETA: {extractor} stage={eta}s, total={total_eta}s, " f"subs={enabled_sub_extractors}, files={len(file_durations)}")
+            logger.info(f"ETA: {extractor} stage={eta}s, total={total_eta}s, subs={enabled_sub_extractors}, files={len(file_durations)}")
 
         # Calculate queue ETA (for all queued batches)
         queue_eta, queued_count = calculate_queue_eta()
@@ -565,7 +565,7 @@ def run_batch_job(batch_id: str, request: BatchRequest) -> None:
                             }
                             update_file_status(i, "running", "motion", motion_result)
                             update_extractor_status(i, "motion", "completed")
-                            logger.info(f"Motion for {fname}: stable={motion.is_stable}, " f"timestamps={len(adaptive_timestamps[i])}")
+                            logger.info(f"Motion for {fname}: stable={motion.is_stable}, timestamps={len(adaptive_timestamps[i])}")
                     except Exception as e:
                         logger.warning(f"Motion analysis failed for {file_path}: {e}")
                         update_extractor_status(i, "motion", "failed")
@@ -743,7 +743,7 @@ def run_batch_job(batch_id: str, request: BatchRequest) -> None:
                                 face_buffer = decode_frames(file_path, timestamps=face_timestamps)
                                 faces = extract_faces(file_path, frame_buffer=face_buffer)
                                 face_frame_count = len(face_buffer.frames)
-                                logger.info(f"Face detection on {face_frame_count} frames for {fname} " f"(short video, {face_fps} FPS)")
+                                logger.info(f"Face detection on {face_frame_count} frames for {fname} (short video, {face_fps} FPS)")
                         else:
                             # Long video - use adaptive batching
                             current_time = 0.0
@@ -802,14 +802,14 @@ def run_batch_job(batch_id: str, request: BatchRequest) -> None:
                                             known_embeddings.extend(new_embs)
                                             consistent_batches = 0
                                             if in_verification_mode:
-                                                logger.info(f"New face detected at {current_time:.1f}s, " "exiting verification mode")
+                                                logger.info(f"New face detected at {current_time:.1f}s, exiting verification mode")
                                                 in_verification_mode = False
                                         elif all_known and known_embeddings:
                                             # All faces are known
                                             consistent_batches += 1
                                             if consistent_batches >= min_consistent_batches and not in_verification_mode:
                                                 in_verification_mode = True
-                                                logger.info(f"Faces stable after {current_time:.1f}s, " "switching to verification mode (every 10s)")
+                                                logger.info(f"Faces stable after {current_time:.1f}s, switching to verification mode (every 10s)")
                                     elif not known_embeddings:
                                         # No faces in this batch and no known faces yet
                                         consistent_batches += 1
@@ -841,15 +841,13 @@ def run_batch_job(batch_id: str, request: BatchRequest) -> None:
                                 )
 
                             mode_info = "verification" if in_verification_mode else "normal"
-                            logger.info(
-                                f"Face detection on {total_frames} frames for {fname} " f"(adaptive batching, {len(known_embeddings)} unique, " f"ended in {mode_info} mode)"
-                            )
+                            logger.info(f"Face detection on {total_frames} frames for {fname} (adaptive batching, {len(known_embeddings)} unique, ended in {mode_info} mode)")
 
                         # Fallback if no duration info
                         if faces is None and buffer is not None:
                             faces = extract_faces(file_path, frame_buffer=buffer)
                             face_frame_count = len(buffer.frames)
-                            logger.info(f"Face detection on {len(buffer.frames)} frames for {fname} " "(using shared buffer)")
+                            logger.info(f"Face detection on {len(buffer.frames)} frames for {fname} (using shared buffer)")
 
                         if faces:
                             faces_data = {
@@ -966,13 +964,17 @@ def run_batch_job(batch_id: str, request: BatchRequest) -> None:
                         timestamps = get_sample_timestamps(motion, max_samples=5)
 
                     file_context = request.contexts.get(file_path) if request.contexts else None
-                    logger.info(f"Calling Qwen with context for {fname}: {file_context}, lut_path={request.lut_path}")
+                    file_batch_overlap = request.visual_batch_overlap.get(file_path, False) if request.visual_batch_overlap else False
+                    file_strategy = request.visual_strategy.get(file_path) if request.visual_strategy else None
+                    logger.info(f"Calling Qwen for {fname}: context={file_context}, lut_path={request.lut_path}, batch_overlap={file_batch_overlap}, strategy={file_strategy}")
                     visual_result = extract_objects_qwen(
                         file_path,
                         timestamps=timestamps,
                         model_name=qwen_model,
                         context=file_context,
                         lut_path=request.lut_path,
+                        batch_overlap=file_batch_overlap,
+                        strategy=file_strategy,
                     )
                     visual_data: dict[str, Any] = {"summary": visual_result.summary}
                     if visual_result.descriptions:

media_engine/batch/timing.py

@@ -126,7 +126,7 @@ def record_timing(
         _timing_history_dirty = True
 
         unit_label = "/unit" if units else "s"
-        logger.debug(f"Recorded timing: {extractor}@{resolution_bucket} = {rate:.2f}{unit_label} " f"(avg: {avg:.2f}{unit_label} from {sample_count} samples)")
+        logger.debug(f"Recorded timing: {extractor}@{resolution_bucket} = {rate:.2f}{unit_label} (avg: {avg:.2f}{unit_label} from {sample_count} samples)")
     # Save periodically (not on every update to reduce disk I/O)
     if _timing_history_dirty and time.time() - _timing_history_last_save > _TIMING_SAVE_INTERVAL:
         save_timing_history()

media_engine/config.py

@@ -81,6 +81,15 @@ class ObjectDetector(StrEnum):
     QWEN = "qwen"
 
 
+class QwenStrategy(StrEnum):
+    """Qwen temporal context strategy for multi-frame analysis."""
+
+    SINGLE = "single"  # No context (current behavior)
+    CONTEXT = "context"  # Pass previous description as text
+    BATCH = "batch"  # Multi-frame batch (2-3 frames together)
+    BATCH_CONTEXT = "batch_context"  # Batch + pass context between groups
+
+
 # =============================================================================
 # Settings (loaded from JSON config file)
 # =============================================================================
@@ -120,6 +129,7 @@ class Settings(BaseModel):
     object_detector: str = DEFAULT_OBJECT_DETECTOR  # "auto", "yolo", or "qwen"
     qwen_model: str = DEFAULT_QWEN_MODEL
     qwen_frames_per_scene: int = DEFAULT_QWEN_FRAMES_PER_SCENE
+    qwen_strategy: str = "auto"  # "auto", "single", "context", "batch", "batch_context"
 
     # YOLO model ("auto" = select based on VRAM)
     yolo_model: str = "auto"
@@ -163,6 +173,12 @@ class Settings(BaseModel):
             return get_auto_object_detector()
         return ObjectDetector(self.object_detector)
 
+    def get_qwen_strategy(self) -> "QwenStrategy":
+        """Get resolved Qwen strategy (handles 'auto')."""
+        if self.qwen_strategy == "auto":
+            return get_auto_qwen_strategy()
+        return QwenStrategy(self.qwen_strategy)
+
 
 def get_config_path() -> Path:
     """Get the config file path."""
@@ -369,7 +385,7 @@ def get_free_memory_gb() -> float:
         # Leave a 1GB buffer for system processes
         available_for_models = max(0.0, available_gb - 1.0)
 
-        logger.info(f"Memory: {mem.total / (1024**3):.0f}GB total, " f"{mem.available / (1024**3):.1f}GB available, " f"{available_for_models:.1f}GB for models")
+        logger.info(f"Memory: {mem.total / (1024**3):.0f}GB total, {mem.available / (1024**3):.1f}GB available, {available_for_models:.1f}GB for models")
         return available_for_models
 
     except ImportError:
@@ -432,46 +448,101 @@ def get_auto_whisper_model() -> str:
 
 
 def get_auto_qwen_model() -> str:
-    """Select Qwen2-VL model based on available VRAM.
+    """Select Qwen2-VL model based on available free memory.
 
-    | VRAM     | Model          | Size  | Quality |
-    |----------|----------------|-------|---------|
-    | <8GB     | (use YOLO)     | -     | Basic   |
-    | 8-16GB   | Qwen2-VL-2B    | ~5GB  | Good    |
-    | 16GB+    | Qwen2-VL-7B    | ~15GB | Best    |
+    | Free Memory | Model          | Size  | Quality |
+    |-------------|----------------|-------|---------|
+    | <8GB        | (use YOLO)     | -     | Basic   |
+    | 8-16GB      | Qwen2-VL-2B    | ~5GB  | Good    |
+    | 16GB+       | Qwen2-VL-7B    | ~15GB | Best    |
     """
-    vram = get_available_vram_gb()
+    free_mem = get_free_memory_gb()
 
-    if vram >= 16:
+    if free_mem >= 16:
         model = "Qwen/Qwen2-VL-7B-Instruct"
-    elif vram >= 8:
+    elif free_mem >= 8:
         model = "Qwen/Qwen2-VL-2B-Instruct"
     else:
-        # Not enough VRAM for Qwen, should use YOLO instead
+        # Not enough free memory for Qwen, should use YOLO instead
         model = "Qwen/Qwen2-VL-2B-Instruct"
-        logger.warning(f"Low VRAM ({vram:.1f}GB) - consider using YOLO instead of Qwen")
+        logger.warning(f"Low free memory ({free_mem:.1f}GB) - consider using YOLO instead of Qwen")
 
-    logger.info(f"Auto-selected Qwen model: {model} (VRAM: {vram:.1f}GB)")
+    logger.info(f"Auto-selected Qwen model: {model} (free memory: {free_mem:.1f}GB)")
     return model
 
 
 def get_auto_object_detector() -> ObjectDetector:
-    """Select object detector based on available VRAM.
+    """Select object detector based on available free memory.
 
     YOLO is faster and uses less memory.
-    Qwen provides better scene understanding but needs more VRAM.
+    Qwen provides better scene understanding but needs more memory.
     """
-    vram = get_available_vram_gb()
+    free_mem = get_free_memory_gb()
 
-    if vram >= 8:
+    if free_mem >= 8:
         detector = ObjectDetector.QWEN
     else:
         detector = ObjectDetector.YOLO
 
-    logger.info(f"Auto-selected object detector: {detector} (VRAM: {vram:.1f}GB)")
+    logger.info(f"Auto-selected object detector: {detector} (free memory: {free_mem:.1f}GB)")
     return detector
 
 
+def get_auto_qwen_strategy() -> QwenStrategy:
+    """Select Qwen temporal context strategy based on available free memory.
+
+    Thresholds based on Qwen 2B with 1080p images (max 1280px width).
+
+    | Free Memory | Strategy      | Frames per Call | Description              |
+    |-------------|---------------|-----------------|--------------------------|
+    | <8GB        | CONTEXT       | 1               | Text context only        |
+    | 8-12GB      | BATCH         | 2-3             | Multi-frame batches      |
+    | 12GB+       | BATCH_CONTEXT | 2-3             | Batches + text context   |
+    """
+    free_mem = get_free_memory_gb()
+
+    if free_mem >= 12:
+        strategy = QwenStrategy.BATCH_CONTEXT
+    elif free_mem >= 8:
+        strategy = QwenStrategy.BATCH
+    else:
+        strategy = QwenStrategy.CONTEXT
+
+    logger.info(f"Auto-selected Qwen strategy: {strategy} (free memory: {free_mem:.1f}GB)")
+    return strategy
+
+
+def get_auto_qwen_batch_size() -> int:
+    """Select Qwen batch size based on available free memory.
+
+    Larger batches provide better temporal context but use more memory.
+    Each additional frame in a batch adds ~0.5-1GB memory overhead.
+
+    | Free Memory | Batch Size | Notes                    |
+    |-------------|------------|--------------------------|
+    | <10GB       | 2          | Minimal batching         |
+    | 10-15GB     | 3          | Default batch size       |
+    | 15-25GB     | 4          | Good temporal context    |
+    | 25-40GB     | 5          | Rich temporal context    |
+    | 40GB+       | 6          | Maximum temporal context |
+    """
+    free_mem = get_free_memory_gb()
+
+    if free_mem >= 40:
+        batch_size = 6
+    elif free_mem >= 25:
+        batch_size = 5
+    elif free_mem >= 15:
+        batch_size = 4
+    elif free_mem >= 10:
+        batch_size = 3
+    else:
+        batch_size = 2
+
+    logger.info(f"Auto-selected Qwen batch size: {batch_size} (free memory: {free_mem:.1f}GB)")
+    return batch_size
+
+
 def get_auto_yolo_model() -> str:
     """Select YOLO model based on available VRAM.
 
@@ -546,6 +617,7 @@ def get_vram_summary() -> dict:
         "free_memory_gb": round(free_mem, 1),
         "auto_whisper_model": get_auto_whisper_model(),
         "auto_qwen_model": get_auto_qwen_model() if vram >= 8 else None,
+        "auto_qwen_strategy": str(get_auto_qwen_strategy()),
         "auto_yolo_model": get_auto_yolo_model(),
         "auto_clip_model": get_auto_clip_model(),
         "auto_object_detector": str(get_auto_object_detector()),
@@ -654,7 +726,7 @@ def check_memory_before_load(model_name: str, clear_memory_func: Any | None = No
     available = vram if device != DeviceType.CPU else ram
 
     if available < required_gb:
-        logger.warning(f"Low memory ({available:.1f}GB available) for {model_name} " f"({required_gb:.1f}GB required)")
+        logger.warning(f"Low memory ({available:.1f}GB available) for {model_name} ({required_gb:.1f}GB required)")
 
         # Try to free memory
         if clear_memory_func is not None:

media_engine/extractors/faces.py

@@ -200,7 +200,7 @@ def extract_faces(
         unique_faces, unique_estimate = _deduplicate_faces(detections, all_embeddings, frame_size=frame_size)
 
         needs_review = sum(1 for f in unique_faces if f.needs_review)
-        logger.info(f"Detected {len(detections)} faces, {unique_estimate} unique, " f"{needs_review} need review")
+        logger.info(f"Detected {len(detections)} faces, {unique_estimate} unique, {needs_review} need review")
 
         return FacesResult(
             count=len(detections),

media_engine/extractors/frame_buffer.py

@@ -286,7 +286,7 @@ def decode_frames(
     out_width = out_width - (out_width % 2)
     out_height = out_height - (out_height % 2)
 
-    logger.info(f"Decoding {len(timestamps)} frames from {file_path} " f"at {out_width}x{out_height}" + (f" (hwaccel={hwaccel})" if hwaccel else ""))
+    logger.info(f"Decoding {len(timestamps)} frames from {file_path} at {out_width}x{out_height}" + (f" (hwaccel={hwaccel})" if hwaccel else ""))
 
     frames: dict[float, SharedFrame] = {}
 

media_engine/extractors/frames.py

@@ -99,7 +99,7 @@ class FrameExtractor:
                 pixels = self._width * self._height
                 max_dim = max(self._width, self._height)
                 if pixels > HIGH_RES_THRESHOLD and max_dim > self.max_dimension:
-                    logger.info(f"High-res video ({self._width}x{self._height}), " f"using FFmpeg decode at {self.max_dimension}px")
+                    logger.info(f"High-res video ({self._width}x{self._height}), using FFmpeg decode at {self.max_dimension}px")
                     self._use_ffmpeg_decode = True
                     # Release opencv capture - we'll use FFmpeg instead
                     self.cap.release()
@@ -279,7 +279,7 @@ class FrameExtractor:
         try:
             # Scale filter that maintains aspect ratio
             # scale=W:H:force_original_aspect_ratio=decrease
-            scale_filter = f"scale={self.max_dimension}:{self.max_dimension}" f":force_original_aspect_ratio=decrease"
+            scale_filter = f"scale={self.max_dimension}:{self.max_dimension}:force_original_aspect_ratio=decrease"
 
             cmd = [
                 "ffmpeg",

media_engine/extractors/metadata/sony.py

@@ -416,7 +416,7 @@ class SonyExtractor:
                     total_duration=recording.total_duration,
                     file_index=file_index,
                 )
-                logger.info(f"Detected spanned recording: file {file_index + 1} of {len(recording.clips)}, " f"total duration {recording.total_duration:.1f}s")
+                logger.info(f"Detected spanned recording: file {file_index + 1} of {len(recording.clips)}, total duration {recording.total_duration:.1f}s")
 
         return Metadata(
             duration=base_metadata.duration,

media_engine/extractors/motion.py

@@ -377,7 +377,7 @@ def analyze_motion(
         total_flow_time += time.perf_counter() - flow_start
 
     # Log timing breakdown
-    logger.info(f"Motion analysis timing: decode={total_load_time:.2f}s, " f"optical_flow={total_flow_time:.2f}s, frames={global_frame_idx}")
+    logger.info(f"Motion analysis timing: decode={total_load_time:.2f}s, optical_flow={total_flow_time:.2f}s, frames={global_frame_idx}")
 
     if not frame_motions:
         return MotionAnalysis(
@@ -693,7 +693,7 @@ def get_adaptive_timestamps(
                 motion.duration * 0.5,
                 motion.duration * 0.85,
             ]
-        logger.info(f"Stable video optimization: {len(timestamps)} frames only " f"(avg_intensity={motion.avg_intensity:.1f})")
+        logger.info(f"Stable video optimization: {len(timestamps)} frames only (avg_intensity={motion.avg_intensity:.1f})")
         return timestamps
 
     if motion.is_stable:
@@ -704,7 +704,7 @@ def get_adaptive_timestamps(
         else:
             step = motion.duration / (num_samples + 1)
             timestamps = [step * (i + 1) for i in range(num_samples)]
-        logger.info(f"Stable video: {len(timestamps)} frames " f"(avg_intensity={motion.avg_intensity:.1f})")
+        logger.info(f"Stable video: {len(timestamps)} frames (avg_intensity={motion.avg_intensity:.1f})")
         return timestamps
 
     if not motion.segments:
@@ -753,7 +753,7 @@ def get_adaptive_timestamps(
     # Ensure timestamps are within video bounds
     timestamps = [max(0.1, min(t, motion.duration - 0.1)) for t in timestamps]
 
-    logger.info(f"Adaptive sampling: {len(timestamps)} frames " f"(avg_intensity={motion.avg_intensity:.1f}, stable={motion.is_stable})")
+    logger.info(f"Adaptive sampling: {len(timestamps)} frames (avg_intensity={motion.avg_intensity:.1f}, stable={motion.is_stable})")
 
     return timestamps
 

media_engine/extractors/objects.py

@@ -157,7 +157,7 @@ def extract_objects(
     # Deduplicate - track unique objects
     unique_detections, summary = _deduplicate_objects(raw_detections)
 
-    logger.info(f"Detected {len(raw_detections)} objects, " f"{len(unique_detections)} unique across {len(summary)} types")
+    logger.info(f"Detected {len(raw_detections)} objects, {len(unique_detections)} unique across {len(summary)} types")
 
     return ObjectsResult(
         summary=summary,