media-engine 0.1.0__py3-none-any.whl

media_engine/extractors/metadata/arri.py

@@ -0,0 +1,118 @@
+"""ARRI metadata extractor.
+
+Detects ARRI cameras (ALEXA, ALEXA Mini, ALEXA 35, AMIRA) via:
+- .ari extension (ARRIRAW)
+- .arx extension (ARRIRAW HDE)
+- .mxf with ARRI metadata
+
+Note: Full ARRIRAW metadata requires ARRI Meta Extract tool (free download).
+Without it, we detect the format but can't read detailed metadata.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from media_engine.schemas import (
+    DetectionMethod,
+    DeviceInfo,
+    MediaDeviceType,
+    Metadata,
+)
+
+from .registry import register_extractor
+
+logger = logging.getLogger(__name__)
+
+# ARRI camera models
+ARRI_MODELS = {
+    "alexa35": "ALEXA 35",
+    "alexa 35": "ALEXA 35",
+    "alexamini": "ALEXA Mini",
+    "alexa mini": "ALEXA Mini",
+    "minilf": "ALEXA Mini LF",
+    "mini lf": "ALEXA Mini LF",
+    "alexalf": "ALEXA LF",
+    "alexa lf": "ALEXA LF",
+    "alexa65": "ALEXA 65",
+    "alexa 65": "ALEXA 65",
+    "amira": "AMIRA",
+    "alexa": "ALEXA",
+}
+
+
+class ArriExtractor:
+    """Extract metadata from ARRI cameras."""
+
+    def detect(self, probe_data: dict[str, Any], file_path: str) -> bool:
+        """Detect if this is an ARRI file."""
+        path = Path(file_path)
+
+        # ARRIRAW extensions
+        if path.suffix.lower() in (".ari", ".arx"):
+            return True
+
+        # Check for ARRI in metadata (for MXF/MOV files)
+        tags = probe_data.get("format", {}).get("tags", {})
+        for value in tags.values():
+            if "arri" in str(value).lower():
+                return True
+
+        # Check stream metadata
+        for stream in probe_data.get("streams", []):
+            stream_tags = stream.get("tags", {})
+            for value in stream_tags.values():
+                if "arri" in str(value).lower():
+                    return True
+
+        return False
+
+    def extract(
+        self,
+        probe_data: dict[str, Any],
+        file_path: str,
+        base_metadata: Metadata,
+    ) -> Metadata:
+        """Extract ARRI-specific metadata."""
+        model = self._detect_model(probe_data, file_path)
+
+        device = DeviceInfo(
+            make="ARRI",
+            model=model,
+            type=MediaDeviceType.CINEMA_CAMERA,
+            detection_method=DetectionMethod.METADATA,
+            confidence=1.0,
+        )
+
+        base_metadata.device = device
+
+        # Note: For full ARRIRAW metadata, would need ARRI Meta Extract
+        # Log a hint for users
+        path = Path(file_path)
+        if path.suffix.lower() in (".ari", ".arx"):
+            logger.info("ARRIRAW detected. For full metadata, install ARRI Meta Extract.")
+
+        return base_metadata
+
+    def _detect_model(self, probe_data: dict[str, Any], file_path: str) -> str | None:
+        """Try to detect ARRI camera model."""
+        # Check all metadata for model hints
+        all_text = ""
+
+        tags = probe_data.get("format", {}).get("tags", {})
+        all_text += " ".join(str(v) for v in tags.values()).lower()
+
+        for stream in probe_data.get("streams", []):
+            stream_tags = stream.get("tags", {})
+            all_text += " ".join(str(v) for v in stream_tags.values()).lower()
+
+        # Search for known models
+        for model_key, model_name in ARRI_MODELS.items():
+            if model_key in all_text:
+                return model_name
+
+        return None
+
+
+# Register the extractor
+register_extractor("arri", ArriExtractor())

media_engine/extractors/metadata/avchd.py

@@ -0,0 +1,208 @@
+"""AVCHD structure parsing for spanned recordings.
+
+AVCHD cameras split long recordings at ~2GB boundaries (FAT32 limit).
+This module detects which MTS files belong to the same recording by
+analyzing timestamps - spanned clips have matching end/start times.
+
+Structure:
+    AVCHD/
+    └── BDMV/
+        ├── CLIPINF/     # Clip info files (.CPI)
+        ├── PLAYLIST/    # Playlist files (.MPL)
+        ├── STREAM/      # Video files (.MTS)
+        └── INDEX.BDM    # Index file
+"""
+
+import logging
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AVCHDClip:
+    """Information about a single AVCHD clip."""
+
+    file_path: str
+    clip_number: int
+    start_time: float  # PTS start time in seconds
+    duration: float
+    file_size: int
+
+
+@dataclass
+class AVCHDRecording:
+    """A recording that may span multiple clips."""
+
+    clips: list[AVCHDClip]
+    total_duration: float
+
+    @property
+    def is_spanned(self) -> bool:
+        return len(self.clips) > 1
+
+    @property
+    def primary_file(self) -> str:
+        """The first file of the recording."""
+        return self.clips[0].file_path
+
+    @property
+    def all_files(self) -> list[str]:
+        """All files in this recording."""
+        return [c.file_path for c in self.clips]
+
+
+def _get_clip_timing(file_path: str) -> tuple[float, float] | None:
+    """Get start time and duration from MTS file.
+
+    Returns:
+        Tuple of (start_time, duration) in seconds, or None if failed.
+    """
+    cmd = [
+        "ffprobe",
+        "-v",
+        "error",
+        "-show_entries",
+        "format=start_time,duration",
+        "-of",
+        "csv=p=0",
+        file_path,
+    ]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        if result.returncode != 0:
+            return None
+
+        parts = result.stdout.strip().split(",")
+        if len(parts) >= 2:
+            start_time = float(parts[0]) if parts[0] else 0
+            duration = float(parts[1]) if parts[1] else 0
+            return start_time, duration
+    except Exception as e:
+        logger.warning(f"Failed to get timing for {file_path}: {e}")
+
+    return None
+
+
+def parse_avchd_structure(avchd_path: str) -> list[AVCHDRecording]:
+    """Parse AVCHD folder structure and identify spanned recordings.
+
+    Args:
+        avchd_path: Path to AVCHD folder or any file within it.
+
+    Returns:
+        List of recordings, each containing one or more clips.
+    """
+    path = Path(avchd_path)
+
+    # Find BDMV/STREAM folder
+    if path.is_file():
+        # Find AVCHD root from file path
+        for parent in path.parents:
+            stream_dir = parent / "BDMV" / "STREAM"
+            if stream_dir.exists():
+                break
+            # Check if we're in STREAM folder
+            if parent.name == "STREAM" and parent.parent.name == "BDMV":
+                stream_dir = parent
+                break
+        else:
+            return []
+    else:
+        stream_dir = path / "BDMV" / "STREAM"
+        if not stream_dir.exists():
+            return []
+
+    # Get all MTS files sorted by number
+    mts_files = sorted(stream_dir.glob("*.MTS"))
+    if not mts_files:
+        mts_files = sorted(stream_dir.glob("*.mts"))
+
+    if not mts_files:
+        return []
+
+    # Get timing for each clip
+    clips: list[AVCHDClip] = []
+    for mts_path in mts_files:
+        timing = _get_clip_timing(str(mts_path))
+        if timing is None:
+            continue
+
+        start_time, duration = timing
+        clip_num = int(mts_path.stem)
+
+        clips.append(
+            AVCHDClip(
+                file_path=str(mts_path),
+                clip_number=clip_num,
+                start_time=start_time,
+                duration=duration,
+                file_size=mts_path.stat().st_size,
+            )
+        )
+
+    if not clips:
+        return []
+
+    # Group clips into recordings based on timestamp continuity
+    # Spanned clips have start_time matching previous clip's end time
+    recordings: list[AVCHDRecording] = []
+    current_group: list[AVCHDClip] = [clips[0]]
+
+    for clip in clips[1:]:
+        prev_clip = current_group[-1]
+        prev_end_time = prev_clip.start_time + prev_clip.duration
+
+        # Check if this clip continues from previous (within 1 second tolerance)
+        if abs(clip.start_time - prev_end_time) < 1.0:
+            # This is a continuation (spanned recording)
+            current_group.append(clip)
+        else:
+            # New recording - save current group and start new one
+            total_dur = sum(c.duration for c in current_group)
+            recordings.append(AVCHDRecording(clips=current_group, total_duration=total_dur))
+            current_group = [clip]
+
+    # Don't forget the last group
+    if current_group:
+        total_dur = sum(c.duration for c in current_group)
+        recordings.append(AVCHDRecording(clips=current_group, total_duration=total_dur))
+
+    return recordings
+
+
+def get_recording_for_file(file_path: str) -> AVCHDRecording | None:
+    """Get the recording that contains the given file.
+
+    Args:
+        file_path: Path to an MTS file.
+
+    Returns:
+        The AVCHDRecording containing this file, or None.
+    """
+    recordings = parse_avchd_structure(file_path)
+    file_path_resolved = str(Path(file_path).resolve())
+
+    for recording in recordings:
+        for clip in recording.clips:
+            if str(Path(clip.file_path).resolve()) == file_path_resolved:
+                return recording
+
+    return None
+
+
+def is_spanned_continuation(file_path: str) -> bool:
+    """Check if this file is a continuation of a spanned recording.
+
+    Returns True if this file is NOT the first file of its recording.
+    """
+    recording = get_recording_for_file(file_path)
+    if recording is None or not recording.is_spanned:
+        return False
+
+    # Check if this is the first file
+    file_path_resolved = str(Path(file_path).resolve())
+    first_file = str(Path(recording.clips[0].file_path).resolve())
+    return file_path_resolved != first_file

media_engine/extractors/metadata/avchd_gps.py

@@ -0,0 +1,270 @@
+"""AVCHD GPS extraction from H.264 SEI MDPM data.
+
+Sony AVCHD cameras (HXR-NX5, HDR-CX series, etc.) embed GPS data
+in the H.264 video stream using MDPM (Modified Digital Video Pack
+Metadata) within SEI NAL units.
+
+The MDPM format is identified by UUID: 17ee8c60-f84d-11d9-8cd6-0800200c9a66
+followed by "MDPM" marker, then tag-value pairs.
+
+GPS tags (from ExifTool H264.pm):
+- 0xB0: GPSVersionID
+- 0xB1: GPSLatitudeRef ('N' or 'S')
+- 0xB2-B4: GPSLatitude (degrees, minutes, seconds as rationals)
+- 0xB5: GPSLongitudeRef ('E' or 'W')
+- 0xB6-B8: GPSLongitude (degrees, minutes, seconds as rationals)
+- 0xB9: GPSAltitudeRef (0=above sea level, 1=below)
+- 0xBA: GPSAltitude
+- 0xBB-BD: GPSTimeStamp (hours, minutes, seconds)
+- 0xBE: GPSStatus ('A'=active, 'V'=void)
+- 0xBF: GPSMeasureMode
+- 0xC0: GPSDOP
+- 0xC2: GPSSpeed
+- 0xCA: GPSDateStamp
+
+Each tag is 1 byte followed by 4 bytes of value data (typically rational).
+"""
+
+import logging
+from pathlib import Path
+
+from media_engine.schemas import GPS, GPSTrack, GPSTrackPoint
+
+logger = logging.getLogger(__name__)
+
+# MDPM UUID used by Sony for embedded metadata in H.264 SEI
+MDPM_UUID = bytes.fromhex("17ee8c60f84d11d98cd60800200c9a66")
+
+
+def _parse_rational(value_bytes: bytes) -> float:
+    """Parse 4-byte rational (2-byte numerator, 2-byte denominator)."""
+    num = (value_bytes[0] << 8) | value_bytes[1]
+    denom = (value_bytes[2] << 8) | value_bytes[3]
+    return num / denom if denom > 0 else float(num)
+
+
+def _extract_gps_from_mdpm_block(mdpm_data: bytes) -> dict[str, float | str] | None:
+    """Extract GPS coordinates from a single MDPM block.
+
+    Returns dict with latitude, longitude, altitude, status or None if invalid.
+    """
+    # Find GPS section start (tag 0xB0)
+    try:
+        gps_start = mdpm_data.index(b"\xb0")
+    except ValueError:
+        return None
+
+    lat_ref: str | None = None
+    lat_deg: float = 0.0
+    lat_min: float = 0.0
+    lat_sec: float = 0.0
+    lon_ref: str | None = None
+    lon_deg: float = 0.0
+    lon_min: float = 0.0
+    lon_sec: float = 0.0
+    altitude: float | None = None
+    status: str = "A"
+
+    i = gps_start
+
+    while i < len(mdpm_data) - 5:
+        tag = mdpm_data[i]
+
+        # Stop if we've passed GPS section
+        if tag > 0xCA and tag < 0xE0:
+            break
+        if tag > 0xE6:
+            break
+
+        # Skip null bytes
+        if tag == 0x00:
+            i += 1
+            continue
+
+        value = mdpm_data[i + 1 : i + 5]
+
+        if tag == 0xB1 and value[0] in (ord("N"), ord("S")):
+            lat_ref = chr(value[0])
+        elif tag == 0xB2:
+            lat_deg = _parse_rational(value)
+        elif tag == 0xB3:
+            lat_min = _parse_rational(value)
+        elif tag == 0xB4:
+            lat_sec = _parse_rational(value)
+        elif tag == 0xB5 and value[0] in (ord("E"), ord("W")):
+            lon_ref = chr(value[0])
+        elif tag == 0xB6:
+            lon_deg = _parse_rational(value)
+        elif tag == 0xB7:
+            lon_min = _parse_rational(value)
+        elif tag == 0xB8:
+            lon_sec = _parse_rational(value)
+        elif tag == 0xBA:
+            altitude = _parse_rational(value)
+        elif tag == 0xBE and value[0] in (ord("A"), ord("V")):
+            status = chr(value[0])
+
+        i += 5
+
+    # Validate complete GPS reading
+    if lat_ref is None or lon_ref is None:
+        return None
+
+    # Convert to decimal degrees
+    lat = lat_deg + lat_min / 60 + lat_sec / 3600
+    if lat_ref == "S":
+        lat = -lat
+
+    lon = lon_deg + lon_min / 60 + lon_sec / 3600
+    if lon_ref == "W":
+        lon = -lon
+
+    result: dict[str, float | str] = {
+        "latitude": round(lat, 6),
+        "longitude": round(lon, 6),
+        "status": status,
+    }
+    if altitude is not None:
+        result["altitude"] = round(altitude, 1)
+
+    return result
+
+
+def extract_avchd_gps(file_path: str) -> GPS | None:
+    """Extract GPS from AVCHD file embedded in H.264 SEI.
+
+    Sony AVCHD cameras embed GPS data in the H.264 video stream using
+    MDPM (Modified Digital Video Pack Metadata) within SEI NAL units.
+
+    Args:
+        file_path: Path to MTS/M2TS file
+
+    Returns:
+        GPS object with first valid GPS point, or None if no GPS found.
+    """
+    path = Path(file_path)
+
+    # Only process MTS/M2TS files (AVCHD)
+    if path.suffix.upper() not in (".MTS", ".M2TS"):
+        return None
+
+    try:
+        with open(file_path, "rb") as f:
+            # Detect packet size (188 for TS, 192 for MTS with timecode)
+            header = f.read(8)
+            f.seek(0)
+
+            if len(header) < 8:
+                return None
+
+            if header[4] == 0x47:
+                # 192-byte packets (4-byte timecode + 188-byte TS)
+                pass  # packet_size = 192
+            elif header[0] == 0x47:
+                # Standard 188-byte TS packets
+                pass  # packet_size = 188
+            else:
+                return None
+
+            # Read file to find MDPM blocks
+            data = f.read()
+
+        # Find first valid GPS point
+        pos = 0
+        while True:
+            pos = data.find(MDPM_UUID, pos)
+            if pos == -1:
+                break
+
+            # Skip UUID (16) + "MDPM" marker (4) = 20 bytes
+            mdpm_start = pos + 20
+            mdpm_data = data[mdpm_start : mdpm_start + 200]
+
+            gps_dict = _extract_gps_from_mdpm_block(mdpm_data)
+
+            if gps_dict and gps_dict.get("status") == "A":
+                lat = gps_dict["latitude"]
+                lon = gps_dict["longitude"]
+                alt = gps_dict.get("altitude")
+
+                # Type narrowing for pyright
+                if isinstance(lat, (int, float)) and isinstance(lon, (int, float)):
+                    gps = GPS(
+                        latitude=float(lat),
+                        longitude=float(lon),
+                        altitude=float(alt) if isinstance(alt, (int, float)) else None,
+                    )
+                    logger.info(f"Extracted GPS from AVCHD SEI: {lat:.6f}, {lon:.6f}")
+                    return gps
+
+            pos += 1
+
+        return None
+
+    except Exception as e:
+        logger.warning(f"Failed to extract AVCHD GPS from {file_path}: {e}")
+        return None
+
+
+def extract_avchd_gps_track(file_path: str, max_points: int = 10000) -> GPSTrack | None:
+    """Extract full GPS track from AVCHD file.
+
+    Args:
+        file_path: Path to MTS/M2TS file
+        max_points: Maximum number of GPS points to extract
+
+    Returns:
+        GPSTrack object with all GPS points, or None if no GPS found.
+    """
+    path = Path(file_path)
+
+    if path.suffix.upper() not in (".MTS", ".M2TS"):
+        return None
+
+    try:
+        with open(file_path, "rb") as f:
+            data = f.read()
+
+        gps_points: list[GPSTrackPoint] = []
+        last_lat: float | None = None
+        last_lon: float | None = None
+        pos = 0
+
+        while len(gps_points) < max_points:
+            pos = data.find(MDPM_UUID, pos)
+            if pos == -1:
+                break
+
+            mdpm_start = pos + 20
+            mdpm_data = data[mdpm_start : mdpm_start + 200]
+
+            gps_dict = _extract_gps_from_mdpm_block(mdpm_data)
+
+            if gps_dict and gps_dict.get("status") == "A":
+                lat = gps_dict["latitude"]
+                lon = gps_dict["longitude"]
+                alt = gps_dict.get("altitude")
+
+                if isinstance(lat, (int, float)) and isinstance(lon, (int, float)):
+                    # Dedupe consecutive identical points
+                    if lat != last_lat or lon != last_lon:
+                        point = GPSTrackPoint(
+                            latitude=float(lat),
+                            longitude=float(lon),
+                            altitude=(float(alt) if isinstance(alt, (int, float)) else None),
+                        )
+                        gps_points.append(point)
+                        last_lat = float(lat)
+                        last_lon = float(lon)
+
+            pos += 1
+
+        if gps_points:
+            logger.info(f"Extracted {len(gps_points)} GPS points from AVCHD SEI")
+            return GPSTrack(points=gps_points, source="avchd_sei")
+
+        return None
+
+    except Exception as e:
+        logger.warning(f"Failed to extract AVCHD GPS track from {file_path}: {e}")
+        return None