kinemotion 0.64.0__py3-none-any.whl → 0.66.0__py3-none-any.whl

kinemotion/core/debug_overlay_utils.py

@@ -1,5 +1,6 @@
 """Shared debug overlay utilities for video rendering."""
 
+# pyright: reportCallIssue=false
 import os
 import shutil
 import subprocess
@@ -12,6 +13,31 @@ from typing_extensions import Self
 
 from .timing import NULL_TIMER, Timer
 
+# Setup logging with structlog support for backend, fallback to standard logging for CLI
+try:
+    import structlog
+
+    logger = structlog.get_logger(__name__)
+    _using_structlog = True
+except ImportError:
+    import logging
+
+    logger = logging.getLogger(__name__)
+    _using_structlog = False
+
+
+def _log(level: str, message: str, **kwargs: object) -> None:
+    """Log message with kwargs support for both structlog and standard logging."""
+    if _using_structlog:
+        getattr(logger, level)(message, **kwargs)
+    else:
+        # For standard logging, format kwargs as part of the message
+        if kwargs:
+            kwargs_str = " ".join(f"{k}={v}" for k, v in kwargs.items())
+            getattr(logger, level)(f"{message} {kwargs_str}")
+        else:
+            getattr(logger, level)(message)
+
 
 def create_video_writer(
     output_path: str,
@@ -24,6 +50,10 @@ def create_video_writer(
     """
     Create a video writer with fallback codec support.
 
+    ⚠️  CRITICAL: DO NOT add "vp09" (VP9) to the codec list!
+    VP9 is not supported on iOS browsers (iPhone/iPad) and causes playback failures.
+    Regression test: tests/core/test_debug_overlay_utils.py::test_vp09_codec_never_in_codec_list
+
     Args:
         output_path: Path for output video
         width: Encoded frame width (from source video)
@@ -38,13 +68,15 @@ def create_video_writer(
     needs_resize = (display_width != width) or (display_height != height)
 
     # Try browser-compatible codecs first
-    # avc1/h264: H.264 (Most compatible)
-    # vp09: VP9 (Good compatibility)
-    # mp4v: MPEG-4 (Poor browser support, last resort)
-    codecs_to_try = ["avc1", "h264", "vp09", "mp4v"]
+    # avc1/h264: H.264 (Most compatible, including iOS)
+    # mp4v: MPEG-4 (Poor browser support, will trigger ffmpeg re-encoding for H.264)
+    # ⚠️  CRITICAL: VP9 (vp09) is EXCLUDED - not supported on iOS/iPhone/iPad browsers!
+    #     Adding VP9 will break debug video playback on all iOS devices.
+    codecs_to_try = ["avc1", "h264", "mp4v"]
 
     writer = None
     used_codec = "mp4v"  # Default fallback
+    codec_attempt_log = []
 
     for codec in codecs_to_try:
         try:
@@ -52,13 +84,36 @@ def create_video_writer(
             writer = cv2.VideoWriter(output_path, fourcc, fps, (display_width, display_height))
             if writer.isOpened():
                 used_codec = codec
+                codec_attempt_log.append({"codec": codec, "status": "success"})
+                _log(
+                    "info",
+                    "debug_video_codec_selected",
+                    codec=codec,
+                    width=display_width,
+                    height=display_height,
+                    fps=fps,
+                )
                 if codec == "mp4v":
-                    print(f"Warning: Fallback to {codec} codec. Video may not play in browsers.")
+                    msg = (
+                        "Using fallback MPEG-4 codec; will re-encode with ffmpeg for "
+                        "browser compatibility"
+                    )
+                    _log("warning", "debug_video_fallback_codec", codec="mp4v", message=msg)
                 break
-        except Exception:
+        except Exception as e:
+            codec_attempt_log.append({"codec": codec, "status": "failed", "error": str(e)})
+            _log("info", "debug_video_codec_attempt_failed", codec=codec, error=str(e))
             continue
 
     if writer is None or not writer.isOpened():
+        _log(
+            "error",
+            "debug_video_writer_creation_failed",
+            output_path=output_path,
+            dimensions=f"{display_width}x{display_height}",
+            fps=fps,
+            codec_attempts=codec_attempt_log,
+        )
         raise ValueError(
             f"Failed to create video writer for {output_path} with dimensions "
             f"{display_width}x{display_height}"
@@ -130,9 +185,35 @@ class BaseDebugOverlayRenderer:
             # Ensure dimensions are even for codec compatibility
             self.display_width = int(display_width * scale) // 2 * 2
             self.display_height = int(display_height * scale) // 2 * 2
+            _log(
+                "info",
+                "debug_video_resolution_optimized",
+                original_width=display_width,
+                original_height=display_height,
+                optimized_width=self.display_width,
+                optimized_height=self.display_height,
+                scale_factor=round(scale, 2),
+            )
         else:
             self.display_width = display_width
             self.display_height = display_height
+            _log(
+                "info",
+                "debug_video_resolution_native",
+                width=self.display_width,
+                height=self.display_height,
+            )
+
+        _log(
+            "info",
+            "debug_overlay_renderer_initialized",
+            output_path=output_path,
+            source_width=width,
+            source_height=height,
+            output_width=self.display_width,
+            output_height=self.display_height,
+            fps=fps,
+        )
 
         # Duration of ffmpeg re-encoding (0.0 if not needed)
         self.reencode_duration_s = 0.0
@@ -174,6 +255,12 @@ class BaseDebugOverlayRenderer:
     def close(self) -> None:
         """Release video writer and re-encode if possible."""
         self.writer.release()
+        _log(
+            "info",
+            "debug_video_writer_released",
+            output_path=self.output_path,
+            codec=self.used_codec,
+        )
 
         # Post-process with ffmpeg ONLY if we fell back to the incompatible mp4v codec
         if self.used_codec == "mp4v" and shutil.which("ffmpeg"):
@@ -187,7 +274,7 @@ class BaseDebugOverlayRenderer:
                 # -y: Overwrite output file
                 # -vcodec libx264: Use H.264 codec
                 # -pix_fmt yuv420p: Required for wide browser support (Chrome,
-                #                   Safari, Firefox)
+                #                   Safari, Firefox, iOS)
                 # -preset fast: Reasonable speed/compression tradeoff
                 # -crf 23: Standard quality
                 # -an: Remove audio (debug video has no audio)
@@ -208,6 +295,16 @@ class BaseDebugOverlayRenderer:
                     temp_path,
                 ]
 
+                _log(
+                    "info",
+                    "debug_video_ffmpeg_reencoding_start",
+                    input_file=self.output_path,
+                    output_file=temp_path,
+                    output_codec="libx264",
+                    pixel_format="yuv420p",
+                    reason="iOS_compatibility",
+                )
+
                 # Suppress output unless error
                 reencode_start = time.time()
                 subprocess.run(
@@ -217,19 +314,54 @@ class BaseDebugOverlayRenderer:
                     stderr=subprocess.PIPE,
                 )
                 self.reencode_duration_s = time.time() - reencode_start
-                print(f"Debug video re-encoded in {self.reencode_duration_s:.2f}s")
+
+                _log(
+                    "info",
+                    "debug_video_ffmpeg_reencoding_complete",
+                    duration_ms=round(self.reencode_duration_s * 1000, 1),
+                )
 
                 # Overwrite original file
                 os.replace(temp_path, self.output_path)
+                _log(
+                    "info",
+                    "debug_video_reencoded_file_replaced",
+                    output_path=self.output_path,
+                    final_codec="libx264",
+                    pixel_format="yuv420p",
+                )
 
             except subprocess.CalledProcessError as e:
-                print(f"Warning: Failed to re-encode debug video with ffmpeg: {e}")
+                stderr_msg = e.stderr.decode("utf-8", errors="ignore") if e.stderr else "N/A"
+                _log(
+                    "warning",
+                    "debug_video_ffmpeg_reencoding_failed",
+                    error=str(e),
+                    stderr=stderr_msg,
+                )
                 if temp_path and os.path.exists(temp_path):
                     os.remove(temp_path)
+                    _log("info", "debug_video_temp_file_cleaned_up", temp_file=temp_path)
             except Exception as e:
-                print(f"Warning: Error during video post-processing: {e}")
+                _log("warning", "debug_video_post_processing_error", error=str(e))
                 if temp_path and os.path.exists(temp_path):
                     os.remove(temp_path)
+                    _log("info", "debug_video_temp_file_cleaned_up", temp_file=temp_path)
+        elif self.used_codec == "mp4v" and not shutil.which("ffmpeg"):
+            _log(
+                "warning",
+                "debug_video_ffmpeg_not_available",
+                codec=self.used_codec,
+                output_path=self.output_path,
+                warning="Video may not play in all browsers",
+            )
+        else:
+            _log(
+                "info",
+                "debug_video_ready_for_playback",
+                codec=self.used_codec,
+                path=self.output_path,
+            )
 
     def __enter__(self) -> Self:
         return self

kinemotion/core/video_io.py

@@ -203,6 +203,17 @@ class VideoProcessor:
         """Release video capture."""
         self.cap.release()
 
+    def __iter__(self) -> "VideoProcessor":
+        """Make the processor iterable."""
+        return self
+
+    def __next__(self) -> np.ndarray:
+        """Get the next frame during iteration."""
+        frame = self.read_frame()
+        if frame is None:
+            raise StopIteration
+        return frame
+
     def __enter__(self) -> "VideoProcessor":
         return self
 

{kinemotion-0.64.0.dist-info → kinemotion-0.66.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.64.0
+Version: 0.66.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

{kinemotion-0.64.0.dist-info → kinemotion-0.66.0.dist-info}/RECORD

@@ -13,7 +13,7 @@ kinemotion/cmj/validation_bounds.py,sha256=Ry915JdInPXbqjaVGNY_urnDO1PAkCSJqHwNK
 kinemotion/core/__init__.py,sha256=U2fnLUGXQ0jbwpXhdksYKDXbeQndEHjn9gwTAEJ9Av0,1451
 kinemotion/core/auto_tuning.py,sha256=lhAqPc-eLjMYx9BCvKdECE7TD2Dweb9KcifV6JHaXOE,11278
 kinemotion/core/cli_utils.py,sha256=sQPbT6XWWau-sm9yuN5c3eS5xNzoQGGXwSz6hQXtRvM,1859
-kinemotion/core/debug_overlay_utils.py,sha256=Ne8GqEWUySwwtkmAzbBs527mh2QsBW2hbgV9CbdJjxE,8441
+kinemotion/core/debug_overlay_utils.py,sha256=Rbmuslc-imondbljiMrQ08JRxaw9TfyFi75nA17sZ9w,13390
 kinemotion/core/determinism.py,sha256=Frw-KAOvAxTL_XtxoWpXCjMbQPUKEAusK6JctlkeuRo,2509
 kinemotion/core/experimental.py,sha256=IK05AF4aZS15ke85hF3TWCqRIXU1AlD_XKzFz735Ua8,3640
 kinemotion/core/filtering.py,sha256=Oc__pV6iHEGyyovbqa5SUi-6v8QyvaRVwA0LRayM884,11355
@@ -26,7 +26,7 @@ kinemotion/core/smoothing.py,sha256=ELMHL7pzSqYffjnLDBUMBJIgt1AwOssDInE8IiXBbig,
 kinemotion/core/timing.py,sha256=d1rjZc07Nbi5Jrio9AC-zeS0dNAlbPyNIydLz7X75Pk,7804
 kinemotion/core/types.py,sha256=A_HclzKpf3By5DiJ0wY9B-dQJrIVAAhUfGab7qTSIL8,1279
 kinemotion/core/validation.py,sha256=0xVv-ftWveV60fJ97kmZMuy2Qqqb5aZLR50dDIrjnhg,6773
-kinemotion/core/video_io.py,sha256=vCwpWnlW2y29l48dFXokdehQn42w_IQvayxbVTjpXqQ,7863
+kinemotion/core/video_io.py,sha256=ufbwfYkxuerat4ab6Hn1tkI5T9TAOvHwREIazJ0Q2tE,8174
 kinemotion/dropjump/__init__.py,sha256=tC3H3BrCg8Oj-db-Vrtx4PH_llR1Ppkd5jwaOjhQcLg,862
 kinemotion/dropjump/analysis.py,sha256=YomuoJF_peyrBSpeT89Q5_sBgY0kEDyq7TFrtEnRLjs,28049
 kinemotion/dropjump/api.py,sha256=uidio49CXisyWKd287CnCrM51GusG9DWAIUKGH85fpM,20584
@@ -36,8 +36,8 @@ kinemotion/dropjump/kinematics.py,sha256=dx4PuXKfKMKcsc_HX6sXj8rHXf9ksiZIOAIkJ4v
 kinemotion/dropjump/metrics_validator.py,sha256=lSfo4Lm5FHccl8ijUP6SA-kcSh50LS9hF8UIyWxcnW8,9243
 kinemotion/dropjump/validation_bounds.py,sha256=x4yjcFxyvdMp5e7MkcoUosGLeGsxBh1Lft6h__AQ2G8,5124
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.64.0.dist-info/METADATA,sha256=yyIEMoc-ce13yauhkU6v4lYI303kW4iACckeBDNhHvo,26061
-kinemotion-0.64.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-kinemotion-0.64.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.64.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.64.0.dist-info/RECORD,,
+kinemotion-0.66.0.dist-info/METADATA,sha256=-fRqQu9C9z3U5xlHHgDeTwIeURdrbv9Kyt1e5hoMrUA,26061
+kinemotion-0.66.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kinemotion-0.66.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.66.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.66.0.dist-info/RECORD,,