media-engine 0.1.0__py3-none-any.whl

media_engine/extractors/metadata/blackmagic.py

@@ -0,0 +1,139 @@
+"""Blackmagic Design metadata extraction.
+
+Handles Blackmagic cameras:
+- Pocket Cinema Camera (4K, 6K, 6K Pro, 6K G2)
+- URSA Mini Pro (4.6K, 12K)
+- Micro Cinema Camera
+- Production Camera 4K
+
+Detection methods:
+- .braw extension (Blackmagic RAW)
+- com.apple.proapps.manufacturer: "Blackmagic Design"
+- com.apple.proapps.cameraname: camera model
+- com.apple.proapps.customgamma: LOG profile
+
+Note: Full BRAW metadata requires Blackmagic RAW SDK (free download).
+Without it, we detect the format but limited metadata from ffprobe.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from media_engine.schemas import (
+    ColorSpace,
+    DetectionMethod,
+    DeviceInfo,
+    MediaDeviceType,
+    Metadata,
+)
+
+from .registry import get_tags_lower, register_extractor
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_custom_gamma(gamma_string: str) -> str | None:
+    """Parse Blackmagic custom gamma string to get LOG profile name.
+
+    Examples:
+        "com.blackmagic-design.productioncamera4k.filmlog" -> "filmlog"
+        "com.blackmagic-design.ursa.film" -> "film"
+    """
+    if not gamma_string:
+        return None
+
+    parts = gamma_string.split(".")
+    if parts:
+        return parts[-1]  # Return the last part as the profile name
+
+    return None
+
+
+class BlackmagicExtractor:
+    """Metadata extractor for Blackmagic Design cameras."""
+
+    def detect(self, probe_data: dict[str, Any], file_path: str) -> bool:
+        """Detect if file is from a Blackmagic camera."""
+        path = Path(file_path)
+
+        # Check for BRAW extension
+        if path.suffix.lower() == ".braw":
+            return True
+
+        tags = get_tags_lower(probe_data)
+
+        # Check ProApps manufacturer tag
+        manufacturer = tags.get("com.apple.proapps.manufacturer", "")
+        if "BLACKMAGIC" in manufacturer.upper():
+            return True
+
+        # Check make tag
+        make = tags.get("make") or tags.get("manufacturer")
+        if make and "BLACKMAGIC" in make.upper():
+            return True
+
+        # Check custom gamma for Blackmagic signature
+        custom_gamma = tags.get("com.apple.proapps.customgamma", "")
+        if "blackmagic" in custom_gamma.lower():
+            return True
+
+        return False
+
+    def extract(self, probe_data: dict[str, Any], file_path: str, base_metadata: Metadata) -> Metadata:
+        """Extract Blackmagic-specific metadata."""
+        path = Path(file_path)
+        tags = get_tags_lower(probe_data)
+
+        # Get device info from ProApps tags (preferred)
+        manufacturer = tags.get("com.apple.proapps.manufacturer") or tags.get("make") or "Blackmagic Design"
+        camera_name = tags.get("com.apple.proapps.cameraname") or tags.get("model")
+
+        # BRAW files are from cinema cameras
+        is_braw = path.suffix.lower() == ".braw"
+        if is_braw:
+            logger.info("BRAW detected. For full metadata, install Blackmagic RAW SDK.")
+
+        device = DeviceInfo(
+            make=manufacturer,
+            model=camera_name,
+            software=tags.get("software"),
+            type=MediaDeviceType.CINEMA_CAMERA,
+            detection_method=DetectionMethod.METADATA,
+            confidence=1.0,
+        )
+
+        # Extract color space from custom gamma
+        color_space = base_metadata.color_space
+        custom_gamma = tags.get("com.apple.proapps.customgamma", "")
+        if custom_gamma:
+            profile_name = _parse_custom_gamma(custom_gamma)
+            if profile_name:
+                base_cs = base_metadata.color_space
+                color_space = ColorSpace(
+                    transfer=profile_name,
+                    primaries=base_cs.primaries if base_cs else None,
+                    matrix=base_cs.matrix if base_cs else None,
+                    detection_method=DetectionMethod.METADATA,
+                )
+
+        return Metadata(
+            duration=base_metadata.duration,
+            resolution=base_metadata.resolution,
+            codec=base_metadata.codec,
+            video_codec=base_metadata.video_codec,
+            audio=base_metadata.audio,
+            fps=base_metadata.fps,
+            bitrate=base_metadata.bitrate,
+            file_size=base_metadata.file_size,
+            timecode=base_metadata.timecode,
+            created_at=base_metadata.created_at,
+            device=device,
+            gps=base_metadata.gps,
+            color_space=color_space,
+            lens=base_metadata.lens,
+        )
+
+
+# Register this extractor
+register_extractor("blackmagic", BlackmagicExtractor())

media_engine/extractors/metadata/camera_360.py

@@ -0,0 +1,276 @@
+"""Generic 360 camera metadata extractor.
+
+Detects 360 cameras from various manufacturers:
+- Insta360 (X3, X4, ONE RS, GO 3, etc.)
+- Kandao QooCam (QooCam 8K, QooCam 3, etc.)
+- GoPro MAX
+- Ricoh Theta
+- Samsung Gear 360
+
+Detection methods:
+- File extension (.insv, .insp for Insta360)
+- Filename patterns (Q360_* for QooCam)
+- Dual video streams with square resolution (unstitched fisheye)
+- 2:1 aspect ratio (stitched equirectangular)
+- Spherical metadata tags
+- Handler names and make/model tags
+"""
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from media_engine.schemas import (
+    DetectionMethod,
+    DeviceInfo,
+    MediaDeviceType,
+    Metadata,
+)
+
+from .registry import get_tags_lower, register_extractor
+
+logger = logging.getLogger(__name__)
+
+
+# Known 360 camera identifiers
+CAMERA_360_BRANDS = {
+    "insta360": {
+        "make": "Insta360",
+        "patterns": [r"INS", r"Insta360"],
+        "extensions": [".insv", ".insp"],
+    },
+    "kandao": {
+        "make": "Kandao",
+        "patterns": [r"Q360_", r"QooCam", r"Kandao"],
+        "extensions": [],
+    },
+    "gopro_max": {
+        "make": "GoPro",
+        "model": "MAX",
+        "patterns": [r"GoPro MAX", r"GPMAX"],
+        "extensions": [".360"],
+    },
+    "ricoh": {
+        "make": "Ricoh",
+        "patterns": [r"RICOH THETA", r"THETA"],
+        "extensions": [],
+    },
+    "samsung": {
+        "make": "Samsung",
+        "patterns": [r"Gear 360", r"SM-R210", r"SM-C200"],
+        "extensions": [],
+    },
+}
+
+
+class Camera360Extractor:
+    """Extract metadata from 360 cameras."""
+
+    def detect(self, probe_data: dict[str, Any], file_path: str) -> bool:
+        """Detect if this is a 360 camera file."""
+        path = Path(file_path)
+        tags = get_tags_lower(probe_data)
+
+        # Check file extensions
+        suffix_lower = path.suffix.lower()
+        for brand_info in CAMERA_360_BRANDS.values():
+            if suffix_lower in brand_info.get("extensions", []):
+                return True
+
+        # Check filename patterns
+        filename = path.name
+        for brand_info in CAMERA_360_BRANDS.values():
+            for pattern in brand_info.get("patterns", []):
+                if re.search(pattern, filename, re.IGNORECASE):
+                    return True
+
+        # Check make/model tags
+        make = tags.get("make", "") or tags.get("manufacturer", "")
+        model = tags.get("model", "")
+        make_model = f"{make} {model}".strip()
+
+        for brand_info in CAMERA_360_BRANDS.values():
+            for pattern in brand_info.get("patterns", []):
+                if re.search(pattern, make_model, re.IGNORECASE):
+                    return True
+
+        # Check handler_name for 360 camera identifiers
+        for stream in probe_data.get("streams", []):
+            handler = stream.get("tags", {}).get("handler_name", "")
+            for brand_info in CAMERA_360_BRANDS.values():
+                for pattern in brand_info.get("patterns", []):
+                    if re.search(pattern, handler, re.IGNORECASE):
+                        return True
+
+        # Check for spherical video metadata
+        if self._has_spherical_metadata(probe_data, tags):
+            return True
+
+        # Check for dual square video streams (unstitched 360)
+        if self._has_dual_fisheye_streams(probe_data):
+            return True
+
+        return False
+
+    def _has_spherical_metadata(self, probe_data: dict[str, Any], tags: dict[str, Any]) -> bool:
+        """Check for spherical/360 video metadata tags."""
+        # Check format tags
+        spherical_keys = [
+            "spherical",
+            "spherical-video",
+            "projection_type",
+            "stereo_mode",
+            "stitching_software",
+        ]
+        for key in spherical_keys:
+            if key in tags:
+                return True
+
+        # Check stream side_data for spherical projection
+        for stream in probe_data.get("streams", []):
+            side_data = stream.get("side_data_list", [])
+            for data in side_data:
+                if data.get("side_data_type") == "Spherical Mapping":
+                    return True
+                if "spherical" in str(data).lower():
+                    return True
+
+        return False
+
+    def _has_dual_fisheye_streams(self, probe_data: dict[str, Any]) -> bool:
+        """Check for dual video streams with square resolution (unstitched 360)."""
+        video_streams = [s for s in probe_data.get("streams", []) if s.get("codec_type") == "video"]
+
+        if len(video_streams) < 2:
+            return False
+
+        # Check if both streams are square (fisheye)
+        square_streams = 0
+        for stream in video_streams:
+            width = stream.get("width", 0)
+            height = stream.get("height", 0)
+            if width > 0 and width == height:
+                square_streams += 1
+
+        return square_streams >= 2
+
+    def extract(
+        self,
+        probe_data: dict[str, Any],
+        file_path: str,
+        base_metadata: Metadata,
+    ) -> Metadata:
+        """Extract 360 camera metadata."""
+        tags = get_tags_lower(probe_data)
+
+        # Detect brand and model
+        make, model = self._detect_brand_model(probe_data, file_path, tags)
+
+        # Detect if it's unstitched (dual fisheye) or stitched (equirectangular)
+        is_unstitched = self._has_dual_fisheye_streams(probe_data)
+
+        device = DeviceInfo(
+            make=make,
+            model=model,
+            type=MediaDeviceType.CAMERA_360,
+            detection_method=DetectionMethod.METADATA,
+            confidence=1.0,
+        )
+
+        # Add note about stitching status in software field
+        if is_unstitched:
+            device.software = "unstitched dual-fisheye"
+
+        base_metadata.device = device
+        return base_metadata
+
+    def _detect_brand_model(
+        self,
+        probe_data: dict[str, Any],
+        file_path: str,
+        tags: dict[str, Any],
+    ) -> tuple[str, str | None]:
+        """Detect 360 camera brand and model."""
+        path = Path(file_path)
+        filename = path.name
+        suffix_lower = path.suffix.lower()
+
+        # Check file extension first
+        for brand_key, brand_info in CAMERA_360_BRANDS.items():
+            if suffix_lower in brand_info.get("extensions", []):
+                model = self._detect_model_from_resolution(probe_data, brand_key)
+                return brand_info["make"], model
+
+        # Check filename patterns
+        if re.search(r"Q360_", filename):
+            model = self._detect_qoocam_model(probe_data)
+            return "Kandao", model
+
+        # Check make/model tags
+        make = tags.get("make", "") or tags.get("manufacturer", "")
+        model = tags.get("model", "")
+
+        if make:
+            # Normalize known brands
+            make_upper = make.upper()
+            if "INSTA" in make_upper:
+                return "Insta360", model or self._detect_model_from_resolution(probe_data, "insta360")
+            if "GOPRO" in make_upper:
+                return "GoPro", model or "MAX"
+            if "RICOH" in make_upper or "THETA" in make_upper:
+                return "Ricoh", model
+            if "SAMSUNG" in make_upper:
+                return "Samsung", model
+            if "KANDAO" in make_upper or "QOOCAM" in make_upper:
+                return "Kandao", model or self._detect_qoocam_model(probe_data)
+
+            return make, model if model else None
+
+        # Check handler for INS prefix (Insta360)
+        for stream in probe_data.get("streams", []):
+            handler = stream.get("tags", {}).get("handler_name", "")
+            if "INS" in handler.upper():
+                return "Insta360", self._detect_model_from_resolution(probe_data, "insta360")
+
+        # Fallback for detected 360 video
+        return "Unknown 360 Camera", None
+
+    def _detect_model_from_resolution(self, probe_data: dict[str, Any], brand: str) -> str | None:
+        """Detect model based on resolution."""
+        video_streams = [s for s in probe_data.get("streams", []) if s.get("codec_type") == "video"]
+
+        for stream in video_streams:
+            width = stream.get("width", 0)
+            height = stream.get("height", 0)
+
+            if brand == "insta360":
+                if width >= 3840 or height >= 3840:
+                    return "X3/X4"
+                elif width >= 2880 or height >= 2880:
+                    return "ONE RS"
+                elif width >= 1920 or height >= 1920:
+                    return "ONE X/X2"
+
+        return None
+
+    def _detect_qoocam_model(self, probe_data: dict[str, Any]) -> str | None:
+        """Detect QooCam model based on resolution and codec."""
+        video_streams = [s for s in probe_data.get("streams", []) if s.get("codec_type") == "video"]
+
+        for stream in video_streams:
+            width = stream.get("width", 0)
+            codec = stream.get("codec_name", "")
+
+            if width >= 3840:
+                if codec == "hevc":
+                    return "8K"  # QooCam 8K uses HEVC
+                return "8K/3"
+            elif width >= 2880:
+                return "3"
+
+        return None
+
+
+# Register the extractor
+register_extractor("camera_360", Camera360Extractor())

media_engine/extractors/metadata/canon.py

@@ -0,0 +1,290 @@
+"""Canon metadata extraction.
+
+Handles Canon cameras:
+- Cinema EOS: C70, C300, C500, etc.
+- EOS R series: R5, R6, R3, etc.
+- DSLRs: 5D, 1DX, etc.
+
+Detection methods:
+- make tag: "Canon"
+- XML sidecar files (.XML)
+
+Canon XML sidecar files contain:
+- Device info (Manufacturer, ModelName)
+- GPS coordinates (Location element)
+- Creation date (CreationDate element)
+
+Canon Cinema EOS MXF filename format:
+- Example: A012C001_230515_BY9X.MXF or A012C001_230515BY9X.MXF
+- The YYMMDD date is embedded after the clip number
+"""
+
+import logging
+import re
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from media_engine.schemas import (
+    GPS,
+    DetectionMethod,
+    DeviceInfo,
+    MediaDeviceType,
+    Metadata,
+)
+
+from .base import SidecarMetadata
+from .registry import get_tags_lower, register_extractor
+
+logger = logging.getLogger(__name__)
+
+# Pattern for Canon Cinema EOS MXF filenames with embedded date
+# Format: A###C###H<YYMMDD><XX>_CANON.MXF
+# Example: A012C001H200529BY_CANON.MXF -> date is 200529 (2020-05-29)
+CANON_DATE_PATTERN = re.compile(r"H(\d{6})", re.IGNORECASE)
+
+
+def _parse_date_from_filename(file_path: str) -> datetime | None:
+    """Extract recording date from Canon MXF filename.
+
+    Canon Cinema EOS cameras encode the date in the filename:
+    - A012C001_230515_BY9X.MXF -> 2023-05-15
+    - A012C001_230515BY9X.MXF -> 2023-05-15
+    - CLIP_230515.MXF -> 2023-05-15
+
+    The date format is YYMMDD (2-digit year, month, day).
+    """
+    filename = Path(file_path).stem
+
+    match = CANON_DATE_PATTERN.search(filename)
+    if not match:
+        return None
+
+    date_str = match.group(1)
+    try:
+        # Parse YYMMDD format
+        year = int(date_str[0:2])
+        month = int(date_str[2:4])
+        day = int(date_str[4:6])
+
+        # Convert 2-digit year to 4-digit (assume 20xx for now)
+        full_year = 2000 + year if year < 70 else 1900 + year
+
+        # Validate date components
+        if not (1 <= month <= 12 and 1 <= day <= 31):
+            return None
+
+        return datetime(full_year, month, day, tzinfo=timezone.utc)
+    except (ValueError, IndexError):
+        return None
+
+
+def _parse_xml_sidecar(video_path: str) -> SidecarMetadata | None:
+    """Parse Canon XML sidecar file for additional metadata.
+
+    Canon cameras create XML sidecar files with naming pattern:
+    - Video: A012C001_230515_BY9X.MXF
+    - XML:   A012C001_230515_BY9X.XML
+    """
+    path = Path(video_path)
+
+    xml_patterns = [
+        path.with_suffix(".XML"),
+        path.with_suffix(".xml"),
+    ]
+
+    xml_path = None
+    for pattern in xml_patterns:
+        if pattern.exists():
+            xml_path = pattern
+            break
+
+    if not xml_path:
+        return None
+
+    try:
+        tree = ET.parse(xml_path)
+        root = tree.getroot()
+
+        ns = {"canon": "http://www.canon.com/ns/VideoClip"}
+
+        device: DeviceInfo | None = None
+        gps: GPS | None = None
+        created_at: datetime | None = None
+
+        # Extract device info
+        device_elem = root.find(".//canon:Device", ns) or root.find(".//{*}Device")
+        if device_elem is not None:
+            manufacturer_elem = device_elem.find("canon:Manufacturer", ns) or device_elem.find("{*}Manufacturer")
+            model_elem = device_elem.find("canon:ModelName", ns) or device_elem.find("{*}ModelName")
+
+            manufacturer = manufacturer_elem.text if manufacturer_elem is not None else None
+            model_name = model_elem.text if model_elem is not None else None
+
+            if manufacturer or model_name:
+                device = DeviceInfo(
+                    make=manufacturer,
+                    model=model_name,
+                    software=None,
+                    type=MediaDeviceType.CAMERA,
+                    detection_method=DetectionMethod.XML_SIDECAR,
+                    confidence=1.0,
+                )
+
+        # Extract creation date - try multiple possible element names
+        date_elements = [
+            ".//canon:CreationDate",
+            ".//canon:StartDate",
+            ".//canon:Date",
+            ".//{*}CreationDate",
+            ".//{*}StartDate",
+            ".//{*}Date",
+        ]
+        for date_xpath in date_elements:
+            if date_xpath.startswith(".//canon:"):
+                date_elem = root.find(date_xpath, ns)
+            else:
+                date_elem = root.find(date_xpath)
+
+            if date_elem is not None and date_elem.text:
+                try:
+                    # Try ISO format first (2023-05-15T10:30:00)
+                    date_text = date_elem.text.strip()
+                    if "T" in date_text:
+                        created_at = datetime.fromisoformat(date_text.replace("Z", "+00:00"))
+                    else:
+                        # Try date only (2023-05-15)
+                        created_at = datetime.strptime(date_text, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+                    break
+                except ValueError:
+                    continue
+
+        # Extract GPS from Location element
+        location_elem = root.find(".//canon:Location", ns) or root.find(".//{*}Location")
+        if location_elem is not None:
+            lat_elem = location_elem.find("canon:Latitude", ns) or location_elem.find("{*}Latitude")
+            lon_elem = location_elem.find("canon:Longitude", ns) or location_elem.find("{*}Longitude")
+            alt_elem = location_elem.find("canon:Altitude", ns) or location_elem.find("{*}Altitude")
+
+            lat = lat_elem.text if lat_elem is not None and lat_elem.text else None
+            lon = lon_elem.text if lon_elem is not None and lon_elem.text else None
+            alt = alt_elem.text if alt_elem is not None and alt_elem.text else None
+
+            if lat and lon:
+                try:
+                    gps = GPS(
+                        latitude=float(lat),
+                        longitude=float(lon),
+                        altitude=float(alt) if alt else None,
+                    )
+                except ValueError:
+                    pass
+
+        if device or gps or created_at:
+            return SidecarMetadata(device=device, gps=gps, created_at=created_at)
+        return None
+
+    except ET.ParseError as e:
+        logger.warning(f"Failed to parse Canon XML sidecar {xml_path}: {e}")
+        return None
+    except Exception as e:
+        logger.warning(f"Error reading Canon XML sidecar {xml_path}: {e}")
+        return None
+
+
+class CanonExtractor:
+    """Metadata extractor for Canon cameras."""
+
+    def detect(self, probe_data: dict[str, Any], file_path: str) -> bool:
+        """Detect if file is from a Canon camera."""
+        tags = get_tags_lower(probe_data)
+
+        # Check make tag (various names used by different formats)
+        make = tags.get("make") or tags.get("manufacturer") or tags.get("company_name")
+        if make and "CANON" in make.upper():
+            return True
+
+        # Check for Canon XML sidecar
+        path = Path(file_path)
+        xml_patterns = [
+            path.with_suffix(".XML"),
+            path.with_suffix(".xml"),
+        ]
+        for pattern in xml_patterns:
+            if pattern.exists():
+                try:
+                    tree = ET.parse(pattern)
+                    root = tree.getroot()
+                    # Check for Canon namespace
+                    if "canon.com" in str(root.tag).lower():
+                        return True
+                    # Check device manufacturer
+                    device = root.find(".//{*}Device")
+                    if device is not None:
+                        mfr_elem = device.find(".//{*}Manufacturer")
+                        if mfr_elem is not None and mfr_elem.text:
+                            if "Canon" in mfr_elem.text:
+                                return True
+                except Exception:
+                    pass
+
+        return False
+
+    def extract(self, probe_data: dict[str, Any], file_path: str, base_metadata: Metadata) -> Metadata:
+        """Extract Canon-specific metadata."""
+        tags = get_tags_lower(probe_data)
+
+        # Get basic device info from tags
+        make = tags.get("make") or tags.get("manufacturer") or "Canon"
+        model = tags.get("model") or tags.get("model_name")
+
+        # Parse XML sidecar for detailed metadata
+        sidecar = _parse_xml_sidecar(file_path)
+
+        # Build device info (prefer sidecar)
+        if sidecar and sidecar.device:
+            device = sidecar.device
+        else:
+            device = DeviceInfo(
+                make=make if make else "Canon",
+                model=model,
+                software=tags.get("software"),
+                type=MediaDeviceType.CAMERA,
+                detection_method=DetectionMethod.METADATA,
+                confidence=1.0,
+            )
+
+        # Merge metadata
+        gps = sidecar.gps if sidecar and sidecar.gps else base_metadata.gps
+
+        # Get creation date: prefer base_metadata, then sidecar, then filename
+        created_at = base_metadata.created_at
+        if created_at is None and sidecar and sidecar.created_at:
+            created_at = sidecar.created_at
+            logger.debug(f"Got creation date from XML sidecar: {created_at}")
+        if created_at is None:
+            created_at = _parse_date_from_filename(file_path)
+            if created_at:
+                logger.debug(f"Parsed creation date from filename: {created_at}")
+
+        return Metadata(
+            duration=base_metadata.duration,
+            resolution=base_metadata.resolution,
+            codec=base_metadata.codec,
+            video_codec=base_metadata.video_codec,
+            audio=base_metadata.audio,
+            fps=base_metadata.fps,
+            bitrate=base_metadata.bitrate,
+            file_size=base_metadata.file_size,
+            timecode=base_metadata.timecode,
+            created_at=created_at,
+            device=device,
+            gps=gps,
+            color_space=base_metadata.color_space,
+            lens=base_metadata.lens,
+        )
+
+
+# Register this extractor
+register_extractor("canon", CanonExtractor())