smart-media-manager 0.5.43a4__py3-none-any.whl

smart_media_manager/metadata_registry.py

@@ -0,0 +1,229 @@
+"""
+Metadata Field Registry Module for Smart Media Manager.
+
+Provides UUID-based metadata field identification for unified field recognition
+across different tools and formats (ExifTool, FFmpeg, libmagic, etc.).
+
+This complements the format UUID system by providing a translation layer for
+metadata field names, enabling programmatic metadata operations across tools.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+LOG = logging.getLogger(__name__)
+
+# Global registry cache
+_METADATA_REGISTRY: Optional[Dict[str, Any]] = None
+
+
+def load_metadata_registry() -> Dict[str, Any]:
+    """Load the metadata field registry from metadata_registry.json.
+
+    Returns:
+        Dictionary containing all metadata field mappings with UUIDs
+    """
+    global _METADATA_REGISTRY
+    if _METADATA_REGISTRY is not None:
+        return _METADATA_REGISTRY
+
+    registry_path = Path(__file__).parent / "metadata_registry.json"
+    if not registry_path.exists():
+        LOG.warning(f"Metadata registry not found at {registry_path}, using empty registry")
+        _METADATA_REGISTRY = {}
+        return _METADATA_REGISTRY
+
+    try:
+        with open(registry_path) as f:
+            _METADATA_REGISTRY = json.load(f)
+            field_count = sum(len(fields) for fields in _METADATA_REGISTRY.get("metadata_fields", {}).values())
+            LOG.info(f"Loaded metadata registry with {field_count} field definitions")
+            return _METADATA_REGISTRY
+    except Exception as exc:
+        LOG.error(f"Failed to load metadata registry: {exc}")
+        _METADATA_REGISTRY = {}
+        return _METADATA_REGISTRY
+
+
+def lookup_metadata_field_uuid(tool_name: str, field_name: str) -> Optional[str]:
+    """Look up metadata field UUID from tool-specific field name.
+
+    Args:
+        tool_name: Name of the tool (exiftool, ffprobe, ffmpeg, etc.)
+        field_name: The field name as reported by the tool
+
+    Returns:
+        Metadata field UUID with -M suffix, or None if not found
+
+    Example:
+        >>> lookup_metadata_field_uuid("exiftool", "EXIF:DateTimeOriginal")
+        '3d4f8a9c-1e7b-5c3d-9a2f-4e8c1b7d3a9f-M'
+        >>> lookup_metadata_field_uuid("ffprobe", "creation_time")
+        '3d4f8a9c-1e7b-5c3d-9a2f-4e8c1b7d3a9f-M'
+    """
+    registry = load_metadata_registry()
+    metadata_fields = registry.get("metadata_fields", {})
+
+    # Search through all categories and fields
+    for category in metadata_fields.values():
+        for field_info in category.values():
+            tool_mappings = field_info.get("tool_mappings", {})
+            if tool_name in tool_mappings:
+                if field_name in tool_mappings[tool_name]:
+                    uuid_value = field_info.get("uuid")
+                    # Ensure we return str or None, not Any
+                    return str(uuid_value) if uuid_value is not None else None
+
+    return None
+
+
+def get_canonical_field_name(field_uuid: str) -> Optional[str]:
+    """Get canonical field name from UUID.
+
+    Args:
+        field_uuid: Metadata field UUID with -M suffix
+
+    Returns:
+        Canonical field name, or None if not found
+
+    Example:
+        >>> get_canonical_field_name("3d4f8a9c-1e7b-5c3d-9a2f-4e8c1b7d3a9f-M")
+        'creation_datetime'
+    """
+    registry = load_metadata_registry()
+    metadata_fields = registry.get("metadata_fields", {})
+
+    for category in metadata_fields.values():
+        for field_info in category.values():
+            if field_info.get("uuid") == field_uuid:
+                canonical_value = field_info.get("canonical")
+                # Ensure we return str or None, not Any
+                return str(canonical_value) if canonical_value is not None else None
+
+    return None
+
+
+def get_tool_field_names(field_uuid: str, tool_name: str) -> List[str]:
+    """Get all tool-specific field names for a UUID.
+
+    Args:
+        field_uuid: Metadata field UUID with -M suffix
+        tool_name: Tool to get field names for (exiftool, ffprobe, etc.)
+
+    Returns:
+        List of field names used by the tool
+
+    Example:
+        >>> get_tool_field_names("3d4f8a9c-...-M", "exiftool")
+        ['EXIF:DateTimeOriginal', 'EXIF:CreateDate', 'XMP:CreateDate']
+    """
+    registry = load_metadata_registry()
+    metadata_fields = registry.get("metadata_fields", {})
+
+    for category in metadata_fields.values():
+        for field_info in category.values():
+            if field_info.get("uuid") == field_uuid:
+                tool_mappings = field_info.get("tool_mappings", {})
+                field_names = tool_mappings.get(tool_name, [])
+                # Ensure we return List[str], not Any - validate each item is a string
+                return [str(name) for name in field_names] if isinstance(field_names, list) else []
+
+    return []
+
+
+def translate_field_name(source_tool: str, source_field: str, target_tool: str) -> Optional[str]:
+    """Translate a field name from one tool to another using UUID mapping.
+
+    Args:
+        source_tool: Tool that reported the field (exiftool, ffprobe, etc.)
+        source_field: Field name as reported by source tool
+        target_tool: Tool to translate field name for
+
+    Returns:
+        First matching field name for target tool, or None if not found
+
+    Example:
+        >>> translate_field_name("exiftool", "EXIF:DateTimeOriginal", "ffprobe")
+        'creation_time'
+        >>> translate_field_name("ffprobe", "creation_time", "exiftool")
+        'EXIF:DateTimeOriginal'
+    """
+    # Look up UUID from source tool's field name
+    field_uuid = lookup_metadata_field_uuid(source_tool, source_field)
+    if not field_uuid:
+        return None
+
+    # Get target tool's field names for this UUID
+    target_fields = get_tool_field_names(field_uuid, target_tool)
+    return target_fields[0] if target_fields else None
+
+
+def normalize_metadata_dict(tool_name: str, metadata: Dict[str, Any]) -> Dict[str, Any]:
+    """Normalize a metadata dictionary to use canonical field names (UUIDs).
+
+    Converts tool-specific field names to UUIDs for tool-agnostic metadata handling.
+
+    Args:
+        tool_name: Tool that produced the metadata (exiftool, ffprobe, etc.)
+        metadata: Dictionary with tool-specific field names
+
+    Returns:
+        Dictionary with UUID keys and original values
+
+    Example:
+        >>> normalize_metadata_dict("ffprobe", {"creation_time": "2024-01-15"})
+        {'3d4f8a9c-1e7b-5c3d-9a2f-4e8c1b7d3a9f-M': '2024-01-15'}
+    """
+    normalized = {}
+    for field_name, value in metadata.items():
+        field_uuid = lookup_metadata_field_uuid(tool_name, field_name)
+        if field_uuid:
+            normalized[field_uuid] = value
+        else:
+            # Preserve unmapped fields with original name
+            LOG.debug(f"No UUID mapping for {tool_name} field: {field_name}")
+            normalized[f"unmapped:{tool_name}:{field_name}"] = value
+
+    return normalized
+
+
+def get_field_description(field_uuid: str) -> Optional[str]:
+    """Get human-readable description of a metadata field.
+
+    Args:
+        field_uuid: Metadata field UUID with -M suffix
+
+    Returns:
+        Field description, or None if not found
+    """
+    registry = load_metadata_registry()
+    metadata_fields = registry.get("metadata_fields", {})
+
+    for category in metadata_fields.values():
+        for field_info in category.values():
+            if field_info.get("uuid") == field_uuid:
+                description_value = field_info.get("description")
+                # Ensure we return str or None, not Any
+                return str(description_value) if description_value is not None else None
+
+    return None
+
+
+def get_all_field_uuids() -> List[str]:
+    """Get list of all metadata field UUIDs in the registry.
+
+    Returns:
+        List of all field UUIDs
+    """
+    registry = load_metadata_registry()
+    metadata_fields = registry.get("metadata_fields", {})
+
+    uuids = []
+    for category in metadata_fields.values():
+        for field_info in category.values():
+            if "uuid" in field_info:
+                uuids.append(field_info["uuid"])
+
+    return uuids

smart_media_manager/uuid_generator.py

@@ -0,0 +1,140 @@
+"""UUID generator for format identification with parameters.
+
+Generates deterministic UUIDs based on format parameters:
+- Codec (h264, hevc, vp9, etc.)
+- Bit depth (8, 10, 12, 16)
+- Pixel format (yuv420p, yuv422p, yuv444p, rgb24, etc.)
+- Profile (high, main, main10, etc.)
+- Sample rate (for audio)
+- Sample format (for audio)
+"""
+
+import hashlib
+from typing import Optional
+
+
+def generate_video_uuid(codec: str, bit_depth: Optional[int] = None, pix_fmt: Optional[str] = None, profile: Optional[str] = None) -> str:
+    """Generate a deterministic UUID for video format.
+
+    Args:
+        codec: Codec name (h264, hevc, vp9, av1, etc.)
+        bit_depth: Bit depth (8, 10, 12, 16)
+        pix_fmt: Pixel format (yuv420p, yuv422p, yuv444p, rgb24, etc.)
+        profile: Codec profile (high, main, main10, etc.)
+
+    Returns:
+        UUID string in format: {hash}-{bitdepth}-{pixfmt}-{profile}-V
+
+    Examples:
+        >>> generate_video_uuid("h264", 8, "yuv420p", "high")
+        'b2e62c4a-6122-548c-9bfa-0fcf3613942a-8bit-yuv420p-high-V'
+    """
+    # Use base codec UUID (for backward compatibility with existing UUIDs)
+    base_uuids = {
+        "h264": "b2e62c4a-6122-548c-9bfa-0fcf3613942a",
+        "hevc": "faf4b553-de47-5bc8-80ea-d026a2571456",
+        "av1": "c69693cd-1fcd-5608-a8df-9476a00cfa9b",
+        "vp9": "4c9b19a7-ec9f-57c2-98ca-3ac8432b27cc",
+    }
+
+    base_uuid = base_uuids.get(codec.lower())
+    if not base_uuid:
+        # Generate deterministic UUID for unknown codec
+        base_uuid = hashlib.sha256(codec.encode()).hexdigest()[:36]
+
+    # If no parameters provided, return base UUID (backward compatibility)
+    if not any([bit_depth, pix_fmt, profile]):
+        return f"{base_uuid}-V"
+
+    # Build parameter suffix
+    params = []
+    if bit_depth:
+        params.append(f"{bit_depth}bit")
+    if pix_fmt:
+        params.append(pix_fmt)
+    if profile:
+        params.append(profile.lower())
+
+    param_suffix = "-".join(params) if params else "default"
+    return f"{base_uuid}-{param_suffix}-V"
+
+
+def generate_audio_uuid(codec: str, sample_rate: Optional[int] = None, sample_fmt: Optional[str] = None) -> str:
+    """Generate a deterministic UUID for audio format.
+
+    Args:
+        codec: Codec name (aac, opus, vorbis, etc.)
+        sample_rate: Sample rate in Hz (44100, 48000, etc.)
+        sample_fmt: Sample format (s16, s24, s32, f32, etc.)
+
+    Returns:
+        UUID string in format: {codec}-{samplerate}-{samplefmt}-A
+
+    Examples:
+        >>> generate_audio_uuid("aac", 48000, "s16")
+        'aac-48000-s16-A'
+    """
+    params = [codec.lower()]
+    if sample_rate:
+        params.append(str(sample_rate))
+    if sample_fmt:
+        params.append(sample_fmt)
+
+    return "-".join(params) + "-A"
+
+
+def parse_video_uuid(uuid: str) -> dict:
+    """Parse a video UUID to extract parameters.
+
+    Args:
+        uuid: Video UUID string
+
+    Returns:
+        Dict with keys: base_uuid, bit_depth, pix_fmt, profile
+
+    Examples:
+        >>> parse_video_uuid("b2e62c4a-6122-548c-9bfa-0fcf3613942a-8bit-yuv420p-high-V")
+        {'base_uuid': 'b2e62c4a-6122-548c-9bfa-0fcf3613942a', 'bit_depth': 8,
+         'pix_fmt': 'yuv420p', 'profile': 'high'}
+    """
+    parts = uuid.split("-")
+
+    result = {"base_uuid": None, "bit_depth": None, "pix_fmt": None, "profile": None}
+
+    # Extract base UUID (first 5 parts: xxxx-xxxx-xxxx-xxxx-xxxx)
+    if len(parts) >= 5:
+        result["base_uuid"] = "-".join(parts[:5])
+
+    # Parse parameter suffix
+    remaining = parts[5:] if len(parts) > 5 else []
+
+    for param in remaining:
+        if param.endswith("bit"):
+            try:
+                result["bit_depth"] = int(param[:-3])
+            except ValueError:
+                pass
+        elif param.startswith("yuv") or param in ("rgb24", "rgba", "gray"):
+            result["pix_fmt"] = param
+        elif param not in ("V", "A", "I", "C", "R"):
+            result["profile"] = param
+
+    return result
+
+
+if __name__ == "__main__":
+    # Test UUID generation
+    print("Video UUIDs:")
+    print(f"  H.264 8-bit 4:2:0 High: {generate_video_uuid('h264', 8, 'yuv420p', 'high')}")
+    print(f"  H.264 10-bit 4:2:0 High10: {generate_video_uuid('h264', 10, 'yuv420p', 'high10')}")
+    print(f"  HEVC 8-bit 4:2:0 Main: {generate_video_uuid('hevc', 8, 'yuv420p', 'main')}")
+    print(f"  HEVC 10-bit 4:2:0 Main10: {generate_video_uuid('hevc', 10, 'yuv420p', 'main10')}")
+
+    print("\nAudio UUIDs:")
+    print(f"  AAC 48kHz 16-bit: {generate_audio_uuid('aac', 48000, 's16')}")
+    print(f"  AAC 6kHz 16-bit: {generate_audio_uuid('aac', 6000, 's16')}")
+
+    print("\nParsing test:")
+    uuid = generate_video_uuid("h264", 10, "yuv420p", "high10")
+    print(f"  UUID: {uuid}")
+    print(f"  Parsed: {parse_video_uuid(uuid)}")