kinemotion 0.50.1__tar.gz → 0.51.0__tar.gz

{kinemotion-0.50.1 → kinemotion-0.51.0}/.github/workflows/deploy-backend.yml

@@ -7,12 +7,20 @@ on:
       - 'backend/**'
       - 'src/kinemotion/**'
       - '.github/workflows/deploy-backend.yml'
-  workflow_dispatch:
-    inputs:
-      reason:
-        description: 'Reason for manual deployment'
-        required: false
-        type: string
+      - '!frontend/**'
+      - '!docs/**'
+      - '!*.md' # ignore markdown files
+      - '!scripts/**'
+      - '!tests/**'
+      - '!.serena/**'
+      - '!.basic-memory/**'
+      - '!.cursor/**'
+      - '!.vscode/**'
+      - '!.gitignore'
+
+concurrency:
+  group: release-all
+  cancel-in-progress: false
 
 env:
   GCP_PROJECT_ID: kinemotion-backend
@@ -68,9 +76,62 @@ jobs:
           cd backend
           uv run ruff check .
 
+  release:
+    name: Create Release
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ steps.get_version.outputs.version }}
+      released: ${{ steps.get_version.outputs.released }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install backend dependencies
+        run: |
+          cd backend
+          uv sync
+
+      - name: Create Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+          cd backend
+          uv run semantic-release version
+
+      - name: Determine version and release status
+        id: get_version
+        run: |
+          # Check if semantic-release created a new release (tagged commit)
+          if git describe --exact-match --tags HEAD 2>/dev/null; then
+            # Semantic release was created - use version from pyproject.toml
+            VERSION=$(grep '^version = ' backend/pyproject.toml | cut -d'"' -f2)
+            RELEASED="true"
+          else
+            # No semantic release - use fallback version (dev-{short_sha})
+            SHORT_SHA=$(git rev-parse --short HEAD)
+            VERSION="dev-${SHORT_SHA}"
+            RELEASED="false"
+          fi
+
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "released=${RELEASED}" >> $GITHUB_OUTPUT
+          echo "Version: ${VERSION} (released: ${RELEASED})"
+
   build:
     name: Build and Push Docker Image to GCR
-    needs: test
+    needs: release
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -99,7 +160,7 @@ jobs:
           context: .
           file: ./backend/Dockerfile
           push: true
-          tags: ${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:${{ github.sha }},${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:latest
+          tags: ${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:${{ needs.release.outputs.version }},${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:${{ github.sha }},${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:latest
           cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:buildcache
           cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:buildcache,mode=max
 

{kinemotion-0.50.1 → kinemotion-0.51.0}/.github/workflows/release.yml

@@ -8,6 +8,20 @@ on:
       - '.github/workflows/deploy-backend.yml'
       - 'backend/**'
       - 'frontend/**'
+      - '*.md' # ignore markdown files
+      - 'scripts/**'
+      - '.serena/**'
+      - '.basic-memory/**'
+      - '.cursor/**'
+      - '.vscode/**'
+      - '.gitignore'
+      - '.claude/**'
+      - '.gemini/**'
+      - '.mcp/**'
+
+concurrency:
+  group: release-all
+  cancel-in-progress: false
 
 jobs:
   test:

{kinemotion-0.50.1 → kinemotion-0.51.0}/.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
         additional_dependencies:
           - mdformat-gfm>=0.3.5  # GitHub Flavored Markdown
           - mdformat-tables  # Table formatting
-        exclude: (^CLAUDE\.md$|^CHANGELOG\.md$|^presentation/revealjs/slides\.md$|\.claude/agents/.*\.md$|\.basic-memory/.*\.md$|\.serena/.*\.md$)
+        exclude: (^CLAUDE\.md$|^CHANGELOG\.md$|^backend/CHANGELOG\.md$|^presentation/revealjs/slides\.md$|\.claude/agents/.*\.md$|\.basic-memory/.*\.md$|\.serena/.*\.md$)
 
   - repo: https://github.com/compilerla/conventional-pre-commit
     rev: v4.3.0

{kinemotion-0.50.1 → kinemotion-0.51.0}/CHANGELOG.md

@@ -7,15 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
-## v0.50.1 (2025-12-14)
+## v0.51.0 (2025-12-13)
 
 ### Bug Fixes
 
-- Fix version
-  ([`e030ed2`](https://github.com/feniix/kinemotion/commit/e030ed2b76315bfcfa21ae61e0d65d99b7e8ba49))
+- Correct MetricsData instantiation and metrics_count calculation
+  ([`e2ebca1`](https://github.com/feniix/kinemotion/commit/e2ebca1d5614faa86cdb3c4e23ef9fa034cd8d2a))
 
-- **backend**: Use configured logger from logging_config
-  ([`e38e3bf`](https://github.com/feniix/kinemotion/commit/e38e3bff973ac47efa9c5735a7e45fead2b219f8))
+- Correct uv.lock path in backend semantic-release build command
+  ([`650c3bc`](https://github.com/feniix/kinemotion/commit/650c3bc7b1a18814f179e7f1e4835000186ee45c))
+
+- Remove invalid search_tag_format and fix tag_format syntax
+  ([`46c2a2a`](https://github.com/feniix/kinemotion/commit/46c2a2af5fa97a833256896253b300c307d3a528))
+
+- Update error handling tests to use 'status' field instead of 'status_code'
+  ([`890e54b`](https://github.com/feniix/kinemotion/commit/890e54b6ac7bead9dceb0f34fdaeb4789e3b3dbd))
+
+- **docs**: Enhance api module docstring with examples and analysis types
+  ([`94e32f1`](https://github.com/feniix/kinemotion/commit/94e32f1061505747c0345e8683a61bcf8dc60ee3))
+
+- **docs**: Improve app.py module docstring with comprehensive feature overview
+  ([`eab977c`](https://github.com/feniix/kinemotion/commit/eab977c237f2318f5dc0b94a32f4b736053bfc00))
+
+- **docs**: Improve module docstrings in src/kinemotion and backend/src/
+  ([`f59d649`](https://github.com/feniix/kinemotion/commit/f59d6494c8735fa3e83f8bdbedefce0b6c405cf5))
+
+### Continuous Integration
+
+- Add semantic-release configuration to backend
+  ([`f8e447c`](https://github.com/feniix/kinemotion/commit/f8e447c86b03d7ad6cf9e40d67217371f642f254))
+
+- Improve workflow configuration and add backend versioning
+  ([`8d86933`](https://github.com/feniix/kinemotion/commit/8d8693398b6aec20c847ae0616488dd3b90c35af))
+
+- Use shared concurrency group to prevent race conditions between CLI and backend release workflows
+  ([`038e744`](https://github.com/feniix/kinemotion/commit/038e744ed13aa52c78557df8257995861de5308e))
+
+### Features
+
+- Add comprehensive granular logging for pipeline stage timing
+  ([`0489222`](https://github.com/feniix/kinemotion/commit/04892221faf2cb39f355867475242b8baafa34cd))
+
+- Implement continuous deployment with optional semantic releases
+  ([`3596e47`](https://github.com/feniix/kinemotion/commit/3596e47e055dd54dda130bba9d7e78c14c4b2819))
+
+### Refactoring
+
+- Decouple semantic-release configs with directory-specific filtering
+  ([`b7d4fef`](https://github.com/feniix/kinemotion/commit/b7d4fefcff2972d2d347dfef69a830b1f2473cfc))
+
+- Namespace semantic-release tags and reset backend to 0.1.0
+  ([`76d9c5b`](https://github.com/feniix/kinemotion/commit/76d9c5b4cedebfd56c5e5ec5272e260620520cd3))
+
+- Restore search_tag_format for decoupled version detection
+  ([`e9f163d`](https://github.com/feniix/kinemotion/commit/e9f163dd85aa81b0dce52d26339bcc858e9b6ef5))
+
+- Separate release job in backend deployment workflow
+  ([`521f03f`](https://github.com/feniix/kinemotion/commit/521f03f4d32c6bcf0b048c2fba3d54d74c7c0677))
 
 
 ## v0.50.0 (2025-12-13)

{kinemotion-0.50.1 → kinemotion-0.51.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.50.1
+Version: 0.51.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.51.0/backend/CHANGELOG.md

@@ -0,0 +1,58 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.1.1 (2025-12-13)
+
+### Bug Fixes
+
+- **docs**: Enhance api module docstring with examples and analysis types
+  ([`94e32f1`](https://github.com/feniix/kinemotion/commit/94e32f1061505747c0345e8683a61bcf8dc60ee3))
+
+
+## v0.1.0 (2025-12-13)
+
+- Initial Release
+
+## v0.1.0 (2025-12-13)
+
+- Initial Release
+
+## v0.52.0 (2025-12-13)
+
+### Features
+
+- Implement continuous deployment with optional semantic releases
+  ([`3596e47`](https://github.com/feniix/kinemotion/commit/3596e47e055dd54dda130bba9d7e78c14c4b2819))
+
+### Refactoring
+
+- Decouple semantic-release configs with directory-specific filtering
+  ([`b7d4fef`](https://github.com/feniix/kinemotion/commit/b7d4fefcff2972d2d347dfef69a830b1f2473cfc))
+
+- Separate release job in backend deployment workflow
+  ([`521f03f`](https://github.com/feniix/kinemotion/commit/521f03f4d32c6bcf0b048c2fba3d54d74c7c0677))
+
+
+## v0.51.0 (2025-12-13)
+
+### Bug Fixes
+
+- Correct MetricsData instantiation and metrics_count calculation
+  ([`e2ebca1`](https://github.com/feniix/kinemotion/commit/e2ebca1d5614faa86cdb3c4e23ef9fa034cd8d2a))
+
+- Update error handling tests to use status field instead of status_code
+  ([`890e54b`](https://github.com/feniix/kinemotion/commit/890e54b6ac7bead9dceb0f34fdaeb4789e3b3dbd))
+
+### Continuous Integration
+
+- Add semantic-release configuration to backend
+  ([`f8e447c`](https://github.com/feniix/kinemotion/commit/f8e447c86b03d7ad6cf9e40d67217371f642f254))
+
+- Improve workflow configuration and add backend versioning
+  ([`8d86933`](https://github.com/feniix/kinemotion/commit/8d8693398b6aec20c847ae0616488dd3b90c35af))
+
+### Features
+
+- Add comprehensive granular logging for pipeline stage timing
+  ([`0489222`](https://github.com/feniix/kinemotion/commit/04892221faf2cb39f355867475242b8baafa34cd))

{kinemotion-0.50.1 → kinemotion-0.51.0}/backend/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion-backend"
-version = "0.1.0"
+version = "0.1.1"
 description = "FastAPI backend for Kinemotion video analysis"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
@@ -59,6 +59,7 @@ dev = [
     "httpx>=0.26.0",
     "ruff>=0.1.8",
     "pyright>=1.1.380",
+    "python-semantic-release>=9.8.2",
 ]
 
 [tool.pytest.ini_options]
@@ -153,3 +154,32 @@ reportUnusedClass = "warning"
 reportUnusedFunction = "warning"
 reportUnusedVariable = "warning"
 reportDuplicateImport = "warning"
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+changelog_file = "CHANGELOG.md"
+tag_format = "kinemotion-backend-v{version}"
+build_command = """\
+    uv lock --upgrade-package "$PACKAGE_NAME"
+    git add ../uv.lock
+    uv build
+"""
+dist_path = "dist/"
+upload_to_vcs_release = true
+remove_dist = false
+patch_without_tag = false
+major_on_zero = false
+allow_zero_version = true
+commit_message = "chore(release): {version} [skip ci]"
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "chore", "build", "ci"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+
+[tool.semantic_release.publish]
+# Only process commits affecting backend/src/kinemotion_backend/ for backend releases
+# Tests (backend/tests/) are excluded since they are not part of the public API
+# This decouples backend versioning from root CLI versioning
+directories = ["backend/src/kinemotion_backend"]

{kinemotion-0.50.1 → kinemotion-0.51.0}/backend/src/kinemotion_backend/analysis_api.py

@@ -1,4 +1,22 @@
-"""API endpoints for analysis sessions and coach feedback."""
+"""API endpoints for analysis sessions and coach feedback.
+
+This module provides FastAPI endpoints for managing video analysis sessions and
+coach feedback. Key responsibilities:
+
+- Create and retrieve analysis sessions for uploaded videos
+- Process video analysis requests through the kinemotion engine
+- Store and retrieve coach feedback linked to analysis sessions
+- Handle authentication via Supabase JWT tokens
+- Manage session state and error handling
+
+Endpoints:
+    POST /api/analysis/sessions - Create a new analysis session
+    GET /api/analysis/sessions/{session_id} - Retrieve session details
+    POST /api/analysis/sessions/{session_id}/feedback - Add coach feedback
+    GET /api/analysis/sessions/{session_id}/feedback - Retrieve feedback
+
+All endpoints require JWT authentication via Authorization header.
+"""
 
 from typing import Any
 

{kinemotion-0.50.1 → kinemotion-0.51.0}/backend/src/kinemotion_backend/app.py

@@ -1,6 +1,18 @@
 """FastAPI application for Kinemotion video analysis backend.
 
-Real metrics integration with Cloudflare R2 storage for video and results management.
+This module provides a REST API for analyzing jump mechanics from video files.
+It handles video uploads, processes them through the kinemotion analysis engine
+(drop jump and counter-movement jump analysis), stores results in Supabase, and
+manages video/result artifacts in Cloudflare R2 storage.
+
+Key features:
+- Video upload and processing for multiple jump types
+- Integration with MediaPipe pose tracking
+- Metrics calculation (RSI, flight time, jump height, etc.)
+- Result persistence in Supabase database
+- Artifact management in Cloudflare R2 storage
+- Rate limiting and request logging middleware
+- CORS support for frontend integration
 """
 
 import os
@@ -78,7 +90,7 @@ class AnalysisResponse:
     def to_dict(self) -> dict[str, Any]:
         """Convert response to JSON-serializable dictionary."""
         result: dict[str, Any] = {
-            "status_code": self.status_code,
+            "status": self.status_code,
             "message": self.message,
             "processing_time_s": self.processing_time_s,
         }
@@ -1145,7 +1157,7 @@ async def http_exception_handler(request: Any, exc: HTTPException) -> JSONRespon
     return JSONResponse(
         status_code=exc.status_code,
         content={
-            "status_code": exc.status_code,
+            "status": exc.status_code,
             "message": "HTTP Error",
             "error": exc.detail,
         },
@@ -1165,7 +1177,7 @@ async def general_exception_handler(request: Any, exc: Exception) -> JSONRespons
     return JSONResponse(
         status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
         content={
-            "status_code": 500,
+            "status": 500,
             "message": "Internal server error",
             "error": error_detail,
         },

{kinemotion-0.50.1 → kinemotion-0.51.0}/backend/src/kinemotion_backend/models/responses.py

@@ -37,7 +37,7 @@ class MetricsData(BaseModel):
 class AnalysisResponse(BaseModel):
     """Response structure for video analysis results."""
 
-    status_code: int = Field(..., description="HTTP status code")
+    status: int = Field(..., description="HTTP status code")
     message: str = Field(..., description="Response message")
     metrics: MetricsData | None = Field(None, description="Analysis metrics")
     results_url: str | None = Field(None, description="URL to analysis results")

{kinemotion-0.50.1 → kinemotion-0.51.0}/backend/src/kinemotion_backend/routes/analysis.py

@@ -1,7 +1,6 @@
 """Video analysis routes for kinemotion backend."""
 
-import time
-
+import structlog
 from fastapi import APIRouter, File, Form, Header, Request, UploadFile
 from fastapi.responses import JSONResponse
 
@@ -13,12 +12,11 @@ except ImportError:
     fastapi_limiter_available = False
     RateLimiter = None  # type: ignore[assignment]
 
-from ..logging_config import get_logger
 from ..models.responses import AnalysisResponse
 from ..services import AnalysisService, validate_referer
 from ..utils import NoOpLimiter
 
-logger = get_logger(__name__)
+logger = structlog.get_logger()
 router = APIRouter(prefix="/api", tags=["Analysis"])
 
 # Rate limiting (use NoOpLimiter for testing or when fastapi_limiter unavailable)
@@ -58,6 +56,8 @@ async def analyze_video(
     Raises:
         HTTPException: If validation or processing fails
     """
+    import time
+
     start_time = time.time()
 
     # Validate referer (prevent direct API access)
@@ -70,12 +70,12 @@ async def analyze_video(
         # Convert debug string to boolean
         enable_debug = debug.lower() == "true"
 
-        # Log analysis start
         logger.info(
-            "analyzing_video_started",
+            "analyze_endpoint_processing",
             jump_type=jump_type,
             quality=quality,
             debug=enable_debug,
+            filename=file.filename,
         )
 
         # Perform analysis using service layer
@@ -87,12 +87,13 @@ async def analyze_video(
             user_id=None,  # TODO: Extract from auth when available
         )
 
-        # Log analysis completion
-        analysis_duration = time.time() - start_time
+        # Log successful response
+        elapsed = time.time() - start_time
         logger.info(
-            "analyzing_video_completed",
-            duration_ms=round(analysis_duration * 1000, 1),
-            status_code=result.status_code,
+            "analyze_endpoint_success",
+            status_code=result.status,
+            processing_time_s=round(elapsed, 2),
+            has_metrics=result.metrics is not None,
         )
 
         # Return JSON response
@@ -109,7 +110,7 @@ async def analyze_video(
 
         # Return validation error
         error_result = AnalysisResponse(
-            status_code=422,
+            status=422,
             message=str(e),
             error="validation_error",
             metrics=None,
@@ -137,7 +138,7 @@ async def analyze_video(
 
         # Return generic server error
         error_result = AnalysisResponse(
-            status_code=500,
+            status=500,
             message="Internal server error during analysis",
             error=str(e),
             metrics=None,

{kinemotion-0.50.1 → kinemotion-0.51.0}/backend/src/kinemotion_backend/services/analysis_service.py

@@ -1,15 +1,15 @@
 import time
 from pathlib import Path
 
+import structlog
 from fastapi import UploadFile
 
-from ..logging_config import get_logger
 from ..models.responses import AnalysisResponse, MetricsData
 from .storage_service import StorageService
 from .validation import validate_jump_type, validate_video_file
 from .video_processor import VideoProcessorService
 
-logger = get_logger(__name__)
+logger = structlog.get_logger(__name__)
 
 
 class AnalysisService:
@@ -49,43 +49,37 @@ class AnalysisService:
         temp_path: str | None = None
         temp_debug_video_path: str | None = None
 
-        # Validate inputs (let ValueError propagate to route handler)
-        logger.info("validating_video_file")
-        validation_start = time.time()
-        validate_video_file(file)
-        validation_duration_ms = (time.time() - validation_start) * 1000
+        # Log analysis start
         logger.info(
-            "validating_video_file_completed",
-            duration_ms=round(validation_duration_ms, 1),
+            "video_analysis_started",
+            jump_type=jump_type,
+            quality=quality,
+            debug_overlay=debug,
+            file_name=file.filename,
         )
 
+        # Validate inputs (let ValueError propagate to route handler)
+        logger.info("validating_video_file", filename=file.filename)
+        validate_video_file(file)
+
         logger.info("validating_jump_type", jump_type=jump_type)
-        jump_type_start = time.time()
         normalized_jump_type = validate_jump_type(jump_type)
-        jump_type_duration_ms = (time.time() - jump_type_start) * 1000
+
         logger.info(
-            "validating_jump_type_completed",
+            "validation_complete",
             normalized_jump_type=normalized_jump_type,
-            duration_ms=round(jump_type_duration_ms, 1),
         )
 
         try:
             # Generate unique storage key
-            logger.info("generating_storage_key", filename=file.filename)
-            key_start = time.time()
+            logger.info("generating_storage_key", original_filename=file.filename)
             storage_key = await self.storage_service.generate_unique_key(
                 file.filename or "video.mp4", user_id
             )
-            key_duration_ms = (time.time() - key_start) * 1000
-            logger.info(
-                "generating_storage_key_completed",
-                storage_key=storage_key,
-                duration_ms=round(key_duration_ms, 1),
-            )
+            logger.info("storage_key_generated", storage_key=storage_key)
 
             # Save uploaded file to temporary location
-            logger.info("saving_uploaded_file", temp_path=temp_path)
-            save_start = time.time()
+            logger.info("saving_uploaded_file", storage_key=storage_key)
             temp_path = self.storage_service.get_temp_file_path(Path(storage_key).name)
             assert temp_path is not None
 
@@ -95,12 +89,12 @@ class AnalysisService:
                 if len(content) > 500 * 1024 * 1024:
                     raise ValueError("File size exceeds maximum of 500MB")
                 temp_file.write(content)
-            save_duration_ms = (time.time() - save_start) * 1000
+
             file_size_mb = len(content) / (1024 * 1024)
             logger.info(
-                "saving_uploaded_file_completed",
+                "uploaded_file_saved",
+                temp_path=temp_path,
                 file_size_mb=round(file_size_mb, 2),
-                duration_ms=round(save_duration_ms, 1),
             )
 
             # Create temporary debug video path if debug is enabled
@@ -191,7 +185,7 @@ class AnalysisService:
             # Log response serialization timing
             serialization_start = time.time()
             response_data = AnalysisResponse(
-                status_code=200,
+                status=200,
                 message="Analysis completed successfully",
                 metrics=MetricsData(**metrics),
                 results_url=results_url,
@@ -256,7 +250,7 @@ class AnalysisService:
                 Path(temp_debug_video_path).unlink(missing_ok=True)
 
             return AnalysisResponse(
-                status_code=500,
+                status=500,
                 message=f"Analysis failed: {str(e)}",
                 error=str(e),
                 metrics=None,

kinemotion-0.51.0/backend/src/kinemotion_backend/services/video_processor.py

@@ -0,0 +1,82 @@
+from typing import Any, cast
+
+import structlog
+from kinemotion import process_cmj_video, process_dropjump_video
+from kinemotion.core.pose import PoseTracker
+from kinemotion.core.timing import Timer
+
+logger = structlog.get_logger(__name__)
+
+
+class VideoProcessorService:
+    """Service for processing video files and extracting kinematic metrics."""
+
+    @staticmethod
+    async def process_video_async(
+        video_path: str,
+        jump_type: str,
+        quality: str = "balanced",
+        output_video: str | None = None,
+        timer: Timer | None = None,
+        pose_tracker: PoseTracker | None = None,
+    ) -> dict[str, Any]:
+        """Process video and return metrics.
+
+        Args:
+            video_path: Path to video file
+            jump_type: Type of jump analysis
+            quality: Analysis quality preset
+            output_video: Optional path for debug video output
+            timer: Optional Timer for measuring operations
+            pose_tracker: Optional shared PoseTracker instance
+
+        Returns:
+            Dictionary with metrics
+
+        Raises:
+            ValueError: If video processing fails
+        """
+        logger.info(
+            "video_processor_starting",
+            jump_type=jump_type,
+            quality=quality,
+            video_path=video_path,
+            has_debug_output=output_video is not None,
+        )
+
+        try:
+            if jump_type == "drop_jump":
+                logger.info("processing_drop_jump_video")
+                metrics = process_dropjump_video(
+                    video_path,
+                    quality=quality,
+                    output_video=output_video,
+                    timer=timer,
+                    pose_tracker=pose_tracker,
+                )
+            else:  # cmj
+                logger.info("processing_cmj_video")
+                metrics = process_cmj_video(
+                    video_path,
+                    quality=quality,
+                    output_video=output_video,
+                    timer=timer,
+                    pose_tracker=pose_tracker,
+                )
+
+            logger.info(
+                "video_processor_completed",
+                jump_type=jump_type,
+                metrics_extracted=True,
+            )
+
+            return cast(dict[str, Any], metrics.to_dict())
+        except Exception as e:
+            logger.error(
+                "video_processor_failed",
+                jump_type=jump_type,
+                error=str(e),
+                error_type=type(e).__name__,
+                exc_info=True,
+            )
+            raise