media-engine 0.1.0__py3-none-any.whl

media_engine/extractors/metadata/gopro.py

@@ -0,0 +1,256 @@
+"""GoPro metadata extractor.
+
+Handles GoPro cameras:
+- HERO5, HERO6, HERO7, HERO8, HERO9, HERO10, HERO11, HERO12, HERO13
+- MAX (360 camera)
+- Session series
+
+Detection methods:
+- handler_name containing "GoPro"
+- firmware tag pattern (e.g., "HD7.01.01.90.00" for HERO7)
+- Filename patterns (GH*, GX*, GOPR*)
+
+GoPro files contain:
+- gpmd stream: GPS, accelerometer, gyroscope data
+- Timecode
+- Color space (usually BT.709)
+"""
+
+import logging
+import struct
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from media_engine.schemas import (
+    GPS,
+    DetectionMethod,
+    DeviceInfo,
+    GPSTrack,
+    GPSTrackPoint,
+    MediaDeviceType,
+    Metadata,
+)
+
+from .registry import get_tags_lower, register_extractor
+
+logger = logging.getLogger(__name__)
+
+# GoPro model mapping from firmware prefix
+GOPRO_MODELS = {
+    "HD5": "HERO5 Black",
+    "HD6": "HERO6 Black",
+    "HD7": "HERO7 Black",
+    "HD8": "HERO8 Black",
+    "HD9": "HERO9 Black",
+    "H10": "HERO10 Black",
+    "H11": "HERO11 Black",
+    "H12": "HERO12 Black",
+    "H13": "HERO13 Black",
+    "H21": "HERO Session",
+    "H22": "HERO5 Session",
+    "HX": "MAX",
+    "H19": "MAX",  # Another MAX identifier
+    "FS": "Fusion",
+}
+
+
+def _parse_firmware_model(firmware: str) -> str | None:
+    """Parse GoPro model from firmware string.
+
+    Examples:
+    - "HD7.01.01.90.00" -> HERO7 Black
+    - "H10.01.01.40.00" -> HERO10 Black
+    """
+    if not firmware:
+        return None
+
+    # Try direct prefix match
+    for prefix, model in GOPRO_MODELS.items():
+        if firmware.upper().startswith(prefix):
+            return model
+
+    return None
+
+
+def _extract_gpmd_gps(file_path: str) -> tuple[GPS | None, GPSTrack | None]:
+    """Extract GPS from GoPro GPMD stream.
+
+    GoPro stores telemetry in a binary stream with FourCC tags.
+    GPS data is under DEVC -> STRM -> GPS5 (lat, lon, alt, speed2d, speed3d).
+
+    Returns tuple of (first GPS point, full GPS track).
+    """
+    try:
+        # Extract gpmd stream using ffmpeg
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-i",
+            file_path,
+            "-codec",
+            "copy",
+            "-map",
+            "0:d:0",  # First data stream (gpmd)
+            "-f",
+            "rawvideo",
+            "pipe:1",
+        ]
+
+        result = subprocess.run(cmd, capture_output=True, timeout=30, check=False)
+
+        if result.returncode != 0 or not result.stdout:
+            return None, None
+
+        data = result.stdout
+        gps_points: list[GPSTrackPoint] = []
+
+        # Parse GPMD binary format
+        # Looking for GPS5 tag which contains: lat, lon, alt, speed2d, speed3d
+        # Each value is a signed 32-bit int, scaled by SCAL value
+
+        i = 0
+        current_scale = 1.0
+
+        while i < len(data) - 8:
+            # Read FourCC tag
+            tag = data[i : i + 4]
+            if len(tag) < 4:
+                break
+
+            # Check for SCAL (scale factor)
+            if tag == b"SCAL":
+                type_byte = data[i + 4] if i + 4 < len(data) else 0
+                size = data[i + 5] if i + 5 < len(data) else 0
+                count = (data[i + 6] << 8 | data[i + 7]) if i + 7 < len(data) else 0
+
+                if type_byte == ord("l") and size == 4 and count >= 1:
+                    # 32-bit signed int scale
+                    scale_offset = i + 8
+                    if scale_offset + 4 <= len(data):
+                        current_scale = struct.unpack(">i", data[scale_offset : scale_offset + 4])[0]
+
+            # Check for GPS5 (GPS data)
+            elif tag == b"GPS5":
+                type_byte = data[i + 4] if i + 4 < len(data) else 0
+                size = data[i + 5] if i + 5 < len(data) else 0
+                count = (data[i + 6] << 8 | data[i + 7]) if i + 7 < len(data) else 0
+
+                if type_byte == ord("l") and size == 20:  # 5 x 4-byte ints
+                    gps_offset = i + 8
+                    for j in range(count):
+                        sample_offset = gps_offset + j * 20
+                        if sample_offset + 20 <= len(data):
+                            values = struct.unpack(">iiiii", data[sample_offset : sample_offset + 20])
+                            lat = values[0] / current_scale
+                            lon = values[1] / current_scale
+                            alt = values[2] / current_scale
+
+                            # Validate coordinates
+                            if -90 <= lat <= 90 and -180 <= lon <= 180 and lat != 0:
+                                point = GPSTrackPoint(
+                                    latitude=round(lat, 6),
+                                    longitude=round(lon, 6),
+                                    altitude=round(alt, 1) if alt != 0 else None,
+                                )
+                                # Dedupe consecutive identical points
+                                if not gps_points or (point.latitude != gps_points[-1].latitude or point.longitude != gps_points[-1].longitude):
+                                    gps_points.append(point)
+
+            i += 1
+
+        if gps_points:
+            first_gps = GPS(
+                latitude=gps_points[0].latitude,
+                longitude=gps_points[0].longitude,
+                altitude=gps_points[0].altitude,
+            )
+            track = GPSTrack(points=gps_points, source="gpmd") if len(gps_points) > 1 else None
+            logger.info(f"Extracted {len(gps_points)} GPS points from GoPro GPMD")
+            return first_gps, track
+
+        return None, None
+
+    except Exception as e:
+        logger.debug(f"Failed to extract GPS from GPMD: {e}")
+        return None, None
+
+
+class GoProExtractor:
+    """Metadata extractor for GoPro cameras."""
+
+    def detect(self, probe_data: dict[str, Any], file_path: str) -> bool:
+        """Detect if file is from a GoPro camera."""
+        path = Path(file_path)
+        tags = get_tags_lower(probe_data)
+
+        # Check firmware tag
+        firmware = tags.get("firmware", "")
+        if firmware and any(firmware.upper().startswith(prefix) for prefix in GOPRO_MODELS):
+            return True
+
+        # Check handler_name for "GoPro"
+        for stream in probe_data.get("streams", []):
+            handler = stream.get("tags", {}).get("handler_name", "")
+            if "GoPro" in handler:
+                return True
+
+        # Check encoder tag
+        for stream in probe_data.get("streams", []):
+            encoder = stream.get("tags", {}).get("encoder", "")
+            if "GoPro" in encoder:
+                return True
+
+        # Check filename pattern (GH*, GX*, GOPR*)
+        name = path.stem.upper()
+        if name.startswith(("GH", "GX", "GOPR")):
+            return True
+
+        return False
+
+    def extract(
+        self,
+        probe_data: dict[str, Any],
+        file_path: str,
+        base_metadata: Metadata,
+    ) -> Metadata:
+        """Extract GoPro-specific metadata."""
+        tags = get_tags_lower(probe_data)
+
+        # Get firmware and parse model
+        firmware = tags.get("firmware", "")
+        model = _parse_firmware_model(firmware)
+
+        # Determine device type (MAX is 360 camera)
+        device_type = MediaDeviceType.ACTION_CAMERA
+        if model and "MAX" in model:
+            device_type = MediaDeviceType.CAMERA_360
+
+        device = DeviceInfo(
+            make="GoPro",
+            model=model,
+            software=firmware if firmware else None,
+            type=device_type,
+            detection_method=DetectionMethod.METADATA,
+            confidence=1.0,
+        )
+
+        # Extract GPS from GPMD stream
+        gps, gps_track = _extract_gpmd_gps(file_path)
+
+        # Use extracted GPS or keep base
+        if gps is None:
+            gps = base_metadata.gps
+        if gps_track is None:
+            gps_track = base_metadata.gps_track
+
+        # Update metadata
+        base_metadata.device = device
+        base_metadata.gps = gps
+        base_metadata.gps_track = gps_track
+
+        return base_metadata
+
+
+# Register the extractor
+register_extractor("gopro", GoProExtractor())

media_engine/extractors/metadata/red.py

@@ -0,0 +1,305 @@
+"""RED Digital Cinema metadata extractor.
+
+Handles RED cameras:
+- RED ONE (2007-2013)
+- SCARLET (2011-2016)
+- EPIC (2010-2016)
+- DRAGON/Weapon (2014-2018)
+- Helium (2016-present)
+- KOMODO (2020-present)
+- V-Raptor (2021-present)
+
+R3D files store metadata in a proprietary header format.
+ffprobe CANNOT read R3D natively, so we parse the header directly.
+
+Header structure (reverse-engineered):
+- 0x00-0x03: Size
+- 0x04-0x07: Magic "RED2"
+- 0x08+: TLV-like blocks with type codes
+
+Notable fields found in header:
+- Timecode (format HH:MM:SS:FF)
+- Date (format YYYYMMDD)
+- Firmware version
+- Camera model (SCARLET, EPIC, KOMODO, etc.)
+- Serial number
+- Lens info (make, model, focal length, aperture)
+"""
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from media_engine.schemas import (
+    Codec,
+    ColorSpace,
+    DetectionMethod,
+    DeviceInfo,
+    LensInfo,
+    MediaDeviceType,
+    Metadata,
+    VideoCodec,
+)
+
+from .registry import register_extractor
+
+logger = logging.getLogger(__name__)
+
+# RED camera models by sensor/body
+RED_MODELS = {
+    "dragon": "RED Dragon",
+    "helium": "RED Helium",
+    "gemini": "RED Gemini",
+    "monstro": "RED Monstro",
+    "komodo": "KOMODO",
+    "raptor": "V-RAPTOR",
+    "ranger": "RANGER",
+    "weapon": "WEAPON",
+    "epic": "EPIC",
+    "scarlet": "SCARLET",
+    "raven": "RAVEN",
+    "red one": "RED ONE",
+    "dsmc2": "DSMC2",
+    "dsmc3": "DSMC3",
+}
+
+
+def _parse_r3d_header(file_path: str) -> dict[str, Any] | None:
+    """Parse R3D file header for metadata.
+
+    Returns dict with extracted metadata or None if not a valid R3D.
+    """
+    try:
+        with open(file_path, "rb") as f:
+            # Read header (first 1KB should contain all metadata)
+            header = f.read(1024)
+
+        if len(header) < 8:
+            return None
+
+        # Check magic
+        magic = header[4:8]
+        if magic != b"RED2":
+            return None
+
+        result: dict[str, Any] = {"make": "RED"}
+
+        # Find timecode (format like "01:00:26:06")
+        tc_match = re.search(rb"\d{2}:\d{2}:\d{2}:\d{2}", header)
+        if tc_match:
+            tc_str = tc_match.group().decode("ascii")
+            result["timecode"] = tc_str
+
+        # Find date (format YYYYMMDD)
+        date_match = re.search(rb"20\d{6}", header)
+        if date_match:
+            date_str = date_match.group().decode("ascii")
+            # Format as YYYY-MM-DD
+            result["date"] = f"{date_str[:4]}-{date_str[4:6]}-{date_str[6:]}"
+
+        # Find firmware version (X.X.XX pattern)
+        fw_match = re.search(rb"\d+\.\d+\.\d+", header)
+        if fw_match:
+            result["firmware"] = fw_match.group().decode("ascii")
+
+        # Find camera model - look for known RED models
+        models = [
+            b"SCARLET",
+            b"EPIC",
+            b"DRAGON",
+            b"WEAPON",
+            b"HELIUM",
+            b"KOMODO",
+            b"RAPTOR",
+            b"RED ONE",
+            b"GEMINI",
+            b"MONSTRO",
+            b"RANGER",
+            b"RAVEN",
+            b"DSMC2",
+            b"DSMC3",
+        ]
+        for model in models:
+            if model in header.upper():
+                result["model"] = model.decode("ascii")
+                break
+
+        # Find serial number (pattern like 221LS102VTLCZ)
+        serial_match = re.search(rb"\d{3}[A-Z]{2}\d{3}[A-Z0-9]+", header)
+        if serial_match:
+            result["serial"] = serial_match.group().decode("ascii")
+
+        # Find lens info (look for known lens brands/patterns)
+        lens_patterns = [
+            rb"Canon [^\x00]+",
+            rb"Zeiss [^\x00]+",
+            rb"Leica [^\x00]+",
+            rb"Sigma [^\x00]+",
+            rb"Cooke [^\x00]+",
+            rb"Angenieux [^\x00]+",
+            rb"Fujinon [^\x00]+",
+            rb"RED [^\x00]*PRO [^\x00]*",
+        ]
+        for pattern in lens_patterns:
+            lens_match = re.search(pattern, header)
+            if lens_match:
+                lens_str = lens_match.group().decode("utf-8", errors="ignore")
+                # Clean up null bytes and control chars
+                lens_str = re.sub(r"[\x00-\x1f]", "", lens_str).strip()
+                if len(lens_str) > 3:
+                    result["lens_name"] = lens_str
+                    break
+
+        # Find lens serial (pattern like 0018-0046-00E6)
+        lens_serial_match = re.search(rb"\d{4}-\d{4}-\d{4}", header)
+        if lens_serial_match:
+            result["lens_serial"] = lens_serial_match.group().decode("ascii")
+
+        return result if len(result) > 1 else None
+
+    except Exception as e:
+        logger.warning(f"Failed to parse R3D header: {e}")
+        return None
+
+
+class RedExtractor:
+    """Extract metadata from RED cameras."""
+
+    def detect(self, probe_data: dict[str, Any], file_path: str) -> bool:
+        """Detect if this is a RED R3D file.
+
+        Detection methods:
+        1. File extension (.R3D)
+        2. RED folder structure (RDM/RDC)
+        3. R3D magic bytes
+        """
+        path = Path(file_path)
+
+        # Check file extension
+        if path.suffix.upper() == ".R3D":
+            return True
+
+        # Check folder structure (RDM = RED Digital Magazine, RDC = RED Digital Clip)
+        parts = path.parts
+        for part in parts:
+            if part.upper().endswith(".RDM") or part.upper().endswith(".RDC"):
+                return True
+
+        return False
+
+    def extract(
+        self,
+        probe_data: dict[str, Any],
+        file_path: str,
+        base_metadata: Metadata,
+    ) -> Metadata:
+        """Extract RED-specific metadata from R3D file."""
+        path = Path(file_path)
+
+        # Parse R3D header directly (ffprobe cannot read R3D)
+        r3d_data = _parse_r3d_header(file_path)
+
+        if r3d_data is None:
+            # Return minimal metadata
+            device = DeviceInfo(
+                make="RED",
+                model=None,
+                type=MediaDeviceType.CINEMA_CAMERA,
+                detection_method=DetectionMethod.METADATA,
+                confidence=0.8,
+            )
+            base_metadata.device = device
+            return base_metadata
+
+        # Build device info
+        # Note: serial_number stored in software field as DeviceInfo doesn't have serial
+        serial = r3d_data.get("serial")
+        firmware = r3d_data.get("firmware")
+        software_str = firmware
+        if serial:
+            software_str = f"{firmware} (S/N: {serial})" if firmware else f"S/N: {serial}"
+
+        device = DeviceInfo(
+            make="RED",
+            model=r3d_data.get("model"),
+            software=software_str,
+            type=MediaDeviceType.CINEMA_CAMERA,
+            detection_method=DetectionMethod.METADATA,
+            confidence=1.0,
+        )
+
+        # Build lens info
+        lens: LensInfo | None = None
+        lens_name = r3d_data.get("lens_name")
+        if lens_name:
+            # Try to parse focal length from lens name
+            focal_match = re.search(r"(\d+)-(\d+)mm|(\d+)mm", lens_name)
+            focal_length: float | None = None
+            if focal_match:
+                if focal_match.group(3):
+                    focal_length = float(focal_match.group(3))
+                elif focal_match.group(1):
+                    # Zoom lens - use wide end
+                    focal_length = float(focal_match.group(1))
+
+            # Try to parse aperture
+            aperture_match = re.search(r"f/?([\d.]+)", lens_name)
+            aperture: float | None = None
+            if aperture_match:
+                aperture = float(aperture_match.group(1))
+
+            # Store lens make/model/serial in iris field as LensInfo lacks those fields
+            lens_serial = r3d_data.get("lens_serial")
+            iris_info = lens_name
+            if lens_serial:
+                iris_info = f"{lens_name} (S/N: {lens_serial})"
+
+            lens = LensInfo(
+                focal_length=focal_length,
+                aperture=aperture,
+                iris=iris_info,  # Store full lens info here
+                detection_method=DetectionMethod.METADATA,
+            )
+
+        # Get timecode string
+        timecode: str | None = r3d_data.get("timecode")
+
+        # Get file size
+        file_size = path.stat().st_size if path.exists() else base_metadata.file_size
+
+        # R3D uses REDCODE compression
+        video_codec = VideoCodec(
+            name="REDCODE",
+            profile="RAW",
+            bit_depth=16,  # RED shoots 16-bit
+        )
+
+        # Color space - RED shoots in REDWideGamutRGB / Log3G10
+        color_space = ColorSpace(
+            primaries="REDWideGamutRGB",
+            transfer="Log3G10",
+            matrix=None,
+            detection_method=DetectionMethod.METADATA,
+        )
+
+        return Metadata(
+            duration=base_metadata.duration,
+            resolution=base_metadata.resolution,
+            codec=Codec(video="REDCODE"),
+            video_codec=video_codec,
+            audio=base_metadata.audio,
+            fps=base_metadata.fps,
+            bitrate=base_metadata.bitrate,
+            file_size=file_size,
+            timecode=timecode,
+            created_at=base_metadata.created_at,
+            device=device,
+            gps=base_metadata.gps,
+            color_space=color_space,
+            lens=lens,
+        )
+
+
+# Register the extractor
+register_extractor("red", RedExtractor())

media_engine/extractors/metadata/registry.py

@@ -0,0 +1,114 @@
+"""Manufacturer detection and extractor registry.
+
+This module provides a registry pattern for metadata extractors.
+Each manufacturer module registers itself with detect() and extract() functions.
+
+To add a new manufacturer:
+1. Create a new module (e.g., panasonic.py)
+2. Implement detect(probe_data, file_path) -> bool
+3. Implement extract(probe_data, file_path, base_metadata) -> Metadata
+4. Import the module in __init__.py to trigger registration
+"""
+
+import logging
+from typing import Any, Protocol
+
+from media_engine.schemas import Metadata
+
+logger = logging.getLogger(__name__)
+
+
+class MetadataExtractor(Protocol):
+    """Protocol for manufacturer-specific metadata extractors."""
+
+    def detect(self, probe_data: dict[str, Any], file_path: str) -> bool:
+        """Detect if this extractor handles the given file.
+
+        Args:
+            probe_data: Parsed ffprobe JSON output
+            file_path: Path to video file
+
+        Returns:
+            True if this extractor should handle the file
+        """
+        ...
+
+    def extract(self, probe_data: dict[str, Any], file_path: str, base_metadata: Metadata) -> Metadata:
+        """Extract manufacturer-specific metadata.
+
+        Args:
+            probe_data: Parsed ffprobe JSON output
+            file_path: Path to video file
+            base_metadata: Base metadata from ffprobe (device-agnostic)
+
+        Returns:
+            Enhanced Metadata with device-specific fields
+        """
+        ...
+
+
+# Global registry of extractors
+_extractors: list[tuple[str, MetadataExtractor]] = []
+
+
+def register_extractor(name: str, extractor: MetadataExtractor) -> None:
+    """Register a metadata extractor.
+
+    Args:
+        name: Extractor name (e.g., "dji", "sony", "apple")
+        extractor: Extractor instance implementing detect() and extract()
+    """
+    _extractors.append((name, extractor))
+    logger.debug(f"Registered metadata extractor: {name}")
+
+
+def get_extractor(probe_data: dict[str, Any], file_path: str) -> tuple[str, MetadataExtractor] | None:
+    """Find the appropriate extractor for a file.
+
+    Iterates through registered extractors in order and returns the first
+    one whose detect() method returns True.
+
+    Args:
+        probe_data: Parsed ffprobe JSON output
+        file_path: Path to video file
+
+    Returns:
+        Tuple of (name, extractor) or None if no match
+    """
+    for name, extractor in _extractors:
+        try:
+            if extractor.detect(probe_data, file_path):
+                logger.debug(f"Matched extractor: {name}")
+                return name, extractor
+        except Exception as e:
+            logger.warning(f"Extractor {name} detect() failed: {e}")
+            continue
+
+    return None
+
+
+def list_extractors() -> list[str]:
+    """List all registered extractor names."""
+    return [name for name, _ in _extractors]
+
+
+# Helper to get common tag values for detection
+def get_tags_lower(probe_data: dict[str, Any]) -> dict[str, str]:
+    """Get format tags with lowercase keys."""
+    format_info = probe_data.get("format", {})
+    tags = format_info.get("tags", {})
+    return {k.lower(): v for k, v in tags.items()}
+
+
+def get_make_model(probe_data: dict[str, Any]) -> tuple[str | None, str | None]:
+    """Extract make and model from common metadata locations.
+
+    Returns:
+        Tuple of (make, model) - either may be None
+    """
+    tags = get_tags_lower(probe_data)
+
+    make = tags.get("make") or tags.get("com.apple.quicktime.make") or tags.get("manufacturer")
+    model = tags.get("model") or tags.get("com.apple.quicktime.model") or tags.get("model_name")
+
+    return make, model