kinemotion 0.19.0__tar.gz → 0.20.1__tar.gz

{kinemotion-0.19.0 → kinemotion-0.20.1}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.20.1 (2025-11-10)
+
+### Bug Fixes
+
+- Add test coverage for ffprobe warning path
+  ([`8ae3e55`](https://github.com/feniix/kinemotion/commit/8ae3e552a3bfb749d4e9bad10c634093db5eddee))
+
+
+## v0.20.0 (2025-11-10)
+
+### Features
+
+- Add platform-specific installation guide and ffprobe warnings
+  ([`b61c8c6`](https://github.com/feniix/kinemotion/commit/b61c8c6dbc2191ca321a2b813aa995c3a68b0b0b))
+
+
 ## v0.19.0 (2025-11-10)
 
 ### Features

{kinemotion-0.19.0 → kinemotion-0.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.19.0
+Version: 0.20.1
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion
@@ -93,27 +93,70 @@ For clinical, research, or performance assessment requiring validated accuracy,
 
 ## Setup
 
-### Prerequisites
+### System Requirements
 
-- [asdf](https://asdf-vm.com/) version manager
-- asdf plugins for Python and uv
+**All Platforms:**
 
-### Installation
+- Python 3.10, 3.11, or 3.12
 
-1. **Install asdf plugins** (if not already installed):
+**Platform-Specific:**
+
+#### Windows
+
+No additional system dependencies required.
+
+**Recommended for mobile video support:**
+
+- [FFmpeg](https://ffmpeg.org/download.html) - Download and add to PATH
+
+#### macOS
+
+No additional system dependencies required.
+
+**Recommended for mobile video support:**
+
+```bash
+brew install ffmpeg
+```
+
+#### Linux (Ubuntu/Debian)
+
+**Recommended system libraries:**
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    ffmpeg
+```
+
+**Note:** `ffmpeg` provides the `ffprobe` tool for video metadata extraction (rotation, aspect ratio). Kinemotion works without it, but mobile/rotated videos may not process correctly. A warning will be shown if `ffprobe` is not available.
+
+### Installation Methods
+
+#### From PyPI (Recommended)
+
+```bash
+pip install kinemotion
+```
+
+#### From Source (Development)
+
+**Step 1:** Install asdf plugins (if not already installed):
 
 ```bash
 asdf plugin add python
 asdf plugin add uv
 ```
 
-1. **Install versions specified in `.tool-versions`**:
+**Step 2:** Install versions specified in `.tool-versions`:
 
 ```bash
 asdf install
 ```
 
-1. **Install project dependencies using uv**:
+**Step 3:** Install project dependencies using uv:
 
 ```bash
 uv sync
@@ -125,7 +168,7 @@ This will install all dependencies and make the `kinemotion` command available.
 
 Kinemotion supports two jump types with intelligent auto-tuning that automatically optimizes parameters based on video characteristics.
 
-### Drop Jump Analysis
+### Analyzing Drop Jumps
 
 Analyzes reactive strength and ground contact time:
 
@@ -134,7 +177,7 @@ Analyzes reactive strength and ground contact time:
 kinemotion dropjump-analyze video.mp4
 ```
 
-### Counter Movement Jump (CMJ) Analysis
+### Analyzing CMJ
 
 Analyzes jump height and biomechanics:
 

{kinemotion-0.19.0 → kinemotion-0.20.1}/README.md

@@ -64,27 +64,70 @@ For clinical, research, or performance assessment requiring validated accuracy,
 
 ## Setup
 
-### Prerequisites
+### System Requirements
 
-- [asdf](https://asdf-vm.com/) version manager
-- asdf plugins for Python and uv
+**All Platforms:**
 
-### Installation
+- Python 3.10, 3.11, or 3.12
 
-1. **Install asdf plugins** (if not already installed):
+**Platform-Specific:**
+
+#### Windows
+
+No additional system dependencies required.
+
+**Recommended for mobile video support:**
+
+- [FFmpeg](https://ffmpeg.org/download.html) - Download and add to PATH
+
+#### macOS
+
+No additional system dependencies required.
+
+**Recommended for mobile video support:**
+
+```bash
+brew install ffmpeg
+```
+
+#### Linux (Ubuntu/Debian)
+
+**Recommended system libraries:**
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    ffmpeg
+```
+
+**Note:** `ffmpeg` provides the `ffprobe` tool for video metadata extraction (rotation, aspect ratio). Kinemotion works without it, but mobile/rotated videos may not process correctly. A warning will be shown if `ffprobe` is not available.
+
+### Installation Methods
+
+#### From PyPI (Recommended)
+
+```bash
+pip install kinemotion
+```
+
+#### From Source (Development)
+
+**Step 1:** Install asdf plugins (if not already installed):
 
 ```bash
 asdf plugin add python
 asdf plugin add uv
 ```
 
-1. **Install versions specified in `.tool-versions`**:
+**Step 2:** Install versions specified in `.tool-versions`:
 
 ```bash
 asdf install
 ```
 
-1. **Install project dependencies using uv**:
+**Step 3:** Install project dependencies using uv:
 
 ```bash
 uv sync
@@ -96,7 +139,7 @@ This will install all dependencies and make the `kinemotion` command available.
 
 Kinemotion supports two jump types with intelligent auto-tuning that automatically optimizes parameters based on video characteristics.
 
-### Drop Jump Analysis
+### Analyzing Drop Jumps
 
 Analyzes reactive strength and ground contact time:
 
@@ -105,7 +148,7 @@ Analyzes reactive strength and ground contact time:
 kinemotion dropjump-analyze video.mp4
 ```
 
-### Counter Movement Jump (CMJ) Analysis
+### Analyzing CMJ
 
 Analyzes jump height and biomechanics:
 

{kinemotion-0.19.0 → kinemotion-0.20.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.19.0"
+version = "0.20.1"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{kinemotion-0.19.0 → kinemotion-0.20.1}/src/kinemotion/core/video_io.py

@@ -2,6 +2,7 @@
 
 import json
 import subprocess
+import warnings
 
 import cv2
 import numpy as np
@@ -147,8 +148,17 @@ class VideoProcessor:
             # Extract rotation from side_data_list (common for iPhone videos)
             self.rotation = self._extract_rotation_from_stream(stream)
 
-        except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
-            # If ffprobe fails, keep original dimensions (square pixels)
+        except FileNotFoundError:
+            # ffprobe not found - warn user about reduced functionality
+            warnings.warn(
+                "ffprobe not found. Video rotation and aspect ratio metadata will be "
+                "ignored. This may cause issues with mobile/rotated videos. "
+                "Install FFmpeg for full video support: https://ffmpeg.org/download.html",
+                UserWarning,
+                stacklevel=2,
+            )
+        except (subprocess.TimeoutExpired, json.JSONDecodeError):
+            # If ffprobe fails for other reasons, silently continue with defaults
             pass
 
     def read_frame(self) -> np.ndarray | None:

{kinemotion-0.19.0 → kinemotion-0.20.1}/tests/test_aspect_ratio.py

@@ -2,9 +2,11 @@
 
 import tempfile
 from pathlib import Path
+from unittest.mock import patch
 
 import cv2
 import numpy as np
+import pytest
 
 from kinemotion.core.video_io import VideoProcessor
 from kinemotion.dropjump.debug_overlay import DebugOverlayRenderer
@@ -98,8 +100,6 @@ def test_aspect_ratio_9_16_portrait():
 
 def test_frame_dimension_validation():
     """Test that mismatched frame dimensions raise an error."""
-    import pytest
-
     output_path = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False).name
 
     try:
@@ -117,3 +117,22 @@ def test_frame_dimension_validation():
 
     finally:
         Path(output_path).unlink(missing_ok=True)
+
+
+def test_ffprobe_not_found_warning():
+    """Test that warning is shown when ffprobe is not available."""
+    test_video = create_test_video(640, 480)
+
+    try:
+        # Mock subprocess.run to raise FileNotFoundError (ffprobe not found)
+        with patch(
+            "subprocess.run", side_effect=FileNotFoundError("ffprobe not found")
+        ):
+            with pytest.warns(
+                UserWarning, match="ffprobe not found.*rotation and aspect ratio"
+            ):
+                video = VideoProcessor(test_video)
+                video.close()
+
+    finally:
+        Path(test_video).unlink()

{kinemotion-0.19.0 → kinemotion-0.20.1}/uv.lock

@@ -700,7 +700,7 @@ wheels = [
 
 [[package]]
 name = "kinemotion"
-version = "0.19.0"
+version = "0.20.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },